Access & discovery

Authentication

Connect with a formal PerchanceAI account API Key or delegated OAuth access token.

Endpoint

GUIDEAuthorization: Bearer <credential>

Authentication & scope

Authorization: Bearer <credential>; formal account API Key / OAuth only.

Sign in to a formal account, open Settings → API & MCP, name an API Key, and copy it from the creation dialog. The complete secret is available only once.

Keep pca_live keys in your server environment. Delegated clients use a formally authorized pca_oauth access token. Include the endpoint's required scope; an API Key or OAuth token spends only its owner's PerchanceAI account credits.

Send the credential only in the Authorization header, never in URLs, logs or storage. Protected API calls have no browser cookie fallback. Anonymous issuance is disabled, and historical pca_anon tokens cannot call business endpoints.

The example checks account credits and requires credits:read. The model catalog and MCP discovery remain public.

Request parameters

Field	Type	Required	Description
`Authorization`	header	Yes	Bearer pca_live_... or Bearer pca_oauth_... from a formal account.

curl --request GET \
  --url 'https://api.perchanceai.art/api/v1/developer/credits' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'Authorization: Bearer <formal_account_credential>'

Response HTTP 200

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

REST success responses contain success, code, message, request_id and data; the table describes data.

Field	Type	Required	Description
`mode`	string	Yes	formal for a formal account credential.
`balance_credits / available_credits / remaining_credits`	integer	Yes	All three currently return the same account credit balance; the unit follows the returned currency.
`currency`	string	Yes	Account currency configuration; never infer a cash balance or fixed pricing from this field.

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "mode": "formal",
    "balance_credits": 120,
    "available_credits": 120,
    "remaining_credits": 120,
    "currency": "USD"
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED
401 — DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT

Missing bearer returns REQUIRED; invalid credentials, including historical anonymous tokens, return INVALID. Expired or revoked credentials use their corresponding codes.

{
  "success": false,
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required.",
  "request_id": "docs-example"
}