openapi: 3.0.0 paths: /v1/models: get: operationId: V1InferenceController_listModels parameters: [] responses: '200': description: '' tags: - Models /v1/chat/completions: post: operationId: V1InferenceController_chatCompletions parameters: [] responses: '401': description: >- `invalid_api_key` — The Bearer API key is missing, malformed, or unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_api_key: summary: invalid_api_key value: error: message: The Bearer API key is missing, malformed, or unknown. type: invalid_request_error code: invalid_api_key '402': description: >- `insufficient_balance` — Account credits balance is below the requested amount. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: insufficient_balance: summary: insufficient_balance value: error: message: Account credits balance is below the requested amount. type: insufficient_quota code: insufficient_balance '403': description: >- `api_key_frozen` — The API key has been administratively frozen. | `model_restricted` — The requested model is not in the key's allowedModels list. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: api_key_frozen: summary: api_key_frozen value: error: message: The API key has been administratively frozen. type: forbidden code: api_key_frozen model_restricted: summary: model_restricted value: error: message: >- The requested model is not in the key's allowedModels list. type: forbidden code: model_restricted '422': description: >- `validation_failed` — Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: validation_failed: summary: validation_failed value: error: message: >- Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. type: invalid_request_error code: validation_failed '429': description: >- `spending_limit_reached` — Per-key daily or monthly spending cap has been exhausted. | `rate_limited` — Caller exceeded the rate-limit window for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: spending_limit_reached: summary: spending_limit_reached value: error: message: >- Per-key daily or monthly spending cap has been exhausted. type: rate_limit_error code: spending_limit_reached rate_limited: summary: rate_limited value: error: message: Caller exceeded the rate-limit window for this endpoint. type: rate_limit_error code: rate_limited '500': description: '`stream_interrupted` — The SSE stream aborted before completion.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: stream_interrupted: summary: stream_interrupted value: error: message: The SSE stream aborted before completion. type: server_error code: stream_interrupted '502': description: >- `all_keys_exhausted` — No contributor key has remaining capacity for the routed model. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: all_keys_exhausted: summary: all_keys_exhausted value: error: message: >- No contributor key has remaining capacity for the routed model. type: server_error code: all_keys_exhausted '503': description: >- `service_unavailable` — A required dependency is down or misconfigured. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: service_unavailable: summary: service_unavailable value: error: message: A required dependency is down or misconfigured. type: server_error code: service_unavailable tags: - Inference /v1/usage: get: operationId: V1InferenceController_usage parameters: [] responses: '401': description: >- `unauthorized` — Authentication is required to access this endpoint. | `invalid_api_key` — The Bearer API key is missing, malformed, or unknown. | `api_key_revoked` — The API key has been revoked and is no longer usable. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: summary: unauthorized value: error: message: Authentication is required to access this endpoint. type: invalid_request_error code: unauthorized invalid_api_key: summary: invalid_api_key value: error: message: The Bearer API key is missing, malformed, or unknown. type: invalid_request_error code: invalid_api_key api_key_revoked: summary: api_key_revoked value: error: message: The API key has been revoked and is no longer usable. type: invalid_request_error code: api_key_revoked '403': description: '`api_key_frozen` — The API key has been administratively frozen.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: api_key_frozen: summary: api_key_frozen value: error: message: The API key has been administratively frozen. type: forbidden code: api_key_frozen tags: - Usage /v1/messages: post: operationId: V1MessagesController_messages parameters: [] responses: '401': description: >- `invalid_api_key` — The Bearer API key is missing, malformed, or unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_api_key: summary: invalid_api_key value: error: message: The Bearer API key is missing, malformed, or unknown. type: invalid_request_error code: invalid_api_key '402': description: >- `insufficient_balance` — Account credits balance is below the requested amount. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: insufficient_balance: summary: insufficient_balance value: error: message: Account credits balance is below the requested amount. type: insufficient_quota code: insufficient_balance '403': description: >- `api_key_frozen` — The API key has been administratively frozen. | `model_restricted` — The requested model is not in the key's allowedModels list. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: api_key_frozen: summary: api_key_frozen value: error: message: The API key has been administratively frozen. type: forbidden code: api_key_frozen model_restricted: summary: model_restricted value: error: message: >- The requested model is not in the key's allowedModels list. type: forbidden code: model_restricted '422': description: >- `validation_failed` — Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: validation_failed: summary: validation_failed value: error: message: >- Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. type: invalid_request_error code: validation_failed '429': description: >- `spending_limit_reached` — Per-key daily or monthly spending cap has been exhausted. | `rate_limited` — Caller exceeded the rate-limit window for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: spending_limit_reached: summary: spending_limit_reached value: error: message: >- Per-key daily or monthly spending cap has been exhausted. type: rate_limit_error code: spending_limit_reached rate_limited: summary: rate_limited value: error: message: Caller exceeded the rate-limit window for this endpoint. type: rate_limit_error code: rate_limited '500': description: '`stream_interrupted` — The SSE stream aborted before completion.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: stream_interrupted: summary: stream_interrupted value: error: message: The SSE stream aborted before completion. type: server_error code: stream_interrupted '502': description: >- `all_keys_exhausted` — No contributor key has remaining capacity for the routed model. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: all_keys_exhausted: summary: all_keys_exhausted value: error: message: >- No contributor key has remaining capacity for the routed model. type: server_error code: all_keys_exhausted '503': description: >- `service_unavailable` — A required dependency is down or misconfigured. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: service_unavailable: summary: service_unavailable value: error: message: A required dependency is down or misconfigured. type: server_error code: service_unavailable tags: - Inference /v1/inference/estimate: get: operationId: InferenceEstimateController_estimate parameters: [] responses: '422': description: >- `validation_failed` — Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: validation_failed: summary: validation_failed value: error: message: >- Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. type: invalid_request_error code: validation_failed '429': description: >- `rate_limited` — Caller exceeded the rate-limit window for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: summary: rate_limited value: error: message: Caller exceeded the rate-limit window for this endpoint. type: rate_limit_error code: rate_limited '503': description: >- `service_unavailable` — A required dependency is down or misconfigured. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: service_unavailable: summary: service_unavailable value: error: message: A required dependency is down or misconfigured. type: server_error code: service_unavailable tags: - Estimate info: title: Compute Finance Inference API description: >- OpenAI- and Anthropic-compatible inference over the Compute Finance provider pool. Point an official SDK at Compute Finance by swapping its base URL and passing a `ct_live_*` API key. Requests are billed against the buyer's `$COMPUTE` balance held in BuyerEscrow at the metered rate published by the Oracle. version: '1.0' contact: name: Compute Finance url: https://compute.finance email: info@compute.finance license: name: MIT url: https://opensource.org/license/mit tags: - name: Inference description: >- Chat completions (OpenAI wire) and messages (Anthropic wire), streaming or single-shot, billed against `$COMPUTE`. - name: Models description: Routable model catalog in OpenAI wire format. - name: Usage description: >- Per-key balance and cumulative counters for the authenticated `ct_live_*` key. - name: Estimate description: >- Pre-flight cost preview for a `(model, promptTokens, completionTokens)` tuple. Unauthenticated, rate-limited. - name: Errors description: >- All API error responses share a unified envelope: ```json { "error": { "message": "...", "type": "...", "code": "" } } ``` Optional fields: `param` (field name), `details` (code-specific payload), `issues[]` (Zod issues for VALIDATION_FAILED). ## Catalog | Code | Status | Type | Meaning | When | |---|---|---|---|---| | `unauthorized` | 401 | `invalid_request_error` | Authentication is required to access this endpoint. | Missing/invalid cf-id JWT cookie, missing Bearer token, or a signed-message timestamp outside the 5-minute freshness window. | | `forbidden` | 403 | `forbidden` | The caller is authenticated but is not allowed to perform this action. | Caller lacks the required role, or a signature verifies to a different address than the authenticated wallet (IDOR guard). | | `invalid_signature` | 401 | `invalid_request_error` | The provided signature could not be recovered or verified. | EIP-191 signature is malformed, truncated, or recovery yielded no valid signer. | | `signature_reused` | 409 | `invalid_request_error` | The signed-request nonce has already been consumed. | Replay protection rejects a second submission with the same nonce. | | `invalid_api_key` | 401 | `invalid_request_error` | The Bearer API key is missing, malformed, or unknown. | Token does not start with `ct_live_`, its SHA-256 hash is not in the database, or the key has been moved to a non-active state on inference endpoints. | | `api_key_frozen` | 403 | `forbidden` | The API key has been administratively frozen. | Buyer or admin froze the key; unfreezing requires manual action. | | `api_key_revoked` | 401 | `invalid_request_error` | The API key has been revoked and is no longer usable. | Buyer revoked the key via /v1/keys/:id/revoke; surfaced canonically on /v1/usage via ApiKeyGuard. | | `model_restricted` | 403 | `forbidden` | The requested model is not in the key's allowedModels list. | Buyer pinned the key to a subset of models; another model was requested. | | `bad_request` | 400 | `invalid_request_error` | The request shape is invalid in a way that does not fit a more specific code. | Generic 400 fallback when no domain-specific factory applies. | | `validation_failed` | 422 | `invalid_request_error` | Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. | Schema-level validation in ZodPipe, or service-level domain validation (e.g. minimum amount). | | `not_found` | 404 | `not_found` | The requested resource does not exist. | Lookup by id/key returned nothing, or the URL does not match any registered route. | | `already_exists` | 409 | `conflict` | A resource with the same unique identity already exists. | Pre-check found a duplicate, or a concurrent insert raised a unique-constraint violation (Prisma P2002). | | `conflict` | 409 | `conflict` | Concurrent modification detected; the client should retry with the latest version. | Serializable-isolation write-skew aborted the transaction (Prisma P2034) or an idempotent operation found inconsistent state. | | `insufficient_balance` | 402 | `insufficient_quota` | Account credits balance is below the requested amount. | Account-level balance check on withdraw or inference billing. | | `spending_limit_reached` | 429 | `rate_limit_error` | Per-key daily or monthly spending cap has been exhausted. | API key carries a `dailyLimit` or `monthlyLimit` and the increment would exceed it. | | `all_keys_exhausted` | 502 | `server_error` | No contributor key has remaining capacity for the routed model. | Router tried every healthy contributor key and each was unavailable, rate-limited, or quarantined. | | `rate_limited` | 429 | `rate_limit_error` | Caller exceeded the rate-limit window for this endpoint. | Throttle interceptor or per-pool RPM/TPM cap rejected the request. | | `stream_interrupted` | 500 | `server_error` | The SSE stream aborted before completion. | Upstream provider connection dropped mid-stream; emitted as an error chunk inside the SSE response, not a status code. | | `contract_error` | 500 | `server_error` | An on-chain call reverted or could not be confirmed. | ethers tx broadcast or wait() failed, or a receipt returned status 0. | | `internal_error` | 500 | `server_error` | Unexpected server-side failure. | Unhandled exception; AppErrorFilter's final fallback. Always paired with a server log. | | `service_unavailable` | 503 | `server_error` | A required dependency is down or misconfigured. | Redis (replay-store, rate limits), Oracle (no confirmed revision), or a downstream service is unreachable. Fail-closed by design on security-critical paths. | servers: - url: https://api.compute.finance description: Production components: securitySchemes: ApiKeyBearer: scheme: bearer bearerFormat: ct_live_* type: http description: >- Send `Authorization: Bearer ct_live_...`. Issue keys at https://compute.finance/dashboard/api-keys. Frozen keys → 403 API_KEY_FROZEN; revoked → 401 API_KEY_REVOKED; unknown → 401 INVALID_API_KEY. ApiKeyHeader: type: apiKey in: header name: x-api-key description: >- Anthropic-SDK compatibility: `x-api-key: ct_live_...`. Accepted only on `POST /v1/messages` so the official `@anthropic-ai/sdk` works with only a base-URL swap. Prefer the Bearer scheme on every other endpoint. schemas: ErrorEnvelope: type: object required: - error properties: error: type: object required: - message - type - code properties: message: type: string description: Human-readable summary. type: type: string description: >- OpenAI-compatible coarse category derived from the canonical code. code: $ref: '#/components/schemas/ErrorCode' param: type: string nullable: true description: Field name when the error is bound to a specific input. details: type: object additionalProperties: true nullable: true description: Code-specific structured payload. issues: type: array items: type: object additionalProperties: true description: Zod issues for VALIDATION_FAILED responses. ErrorCode: type: string description: Canonical taxonomy code. Full descriptions live under the `Errors` tag. enum: - unauthorized - forbidden - invalid_signature - signature_reused - invalid_api_key - api_key_frozen - api_key_revoked - model_restricted - bad_request - validation_failed - not_found - already_exists - conflict - insufficient_balance - spending_limit_reached - all_keys_exhausted - rate_limited - stream_interrupted - contract_error - internal_error - service_unavailable responses: Error_unauthorized: description: 401 unauthorized — Authentication is required to access this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: Authentication is required to access this endpoint. type: invalid_request_error code: unauthorized Error_forbidden: description: >- 403 forbidden — The caller is authenticated but is not allowed to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: >- The caller is authenticated but is not allowed to perform this action. type: forbidden code: forbidden Error_invalid_signature: description: >- 401 invalid_signature — The provided signature could not be recovered or verified. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The provided signature could not be recovered or verified. type: invalid_request_error code: invalid_signature Error_signature_reused: description: >- 409 signature_reused — The signed-request nonce has already been consumed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The signed-request nonce has already been consumed. type: invalid_request_error code: signature_reused Error_invalid_api_key: description: >- 401 invalid_api_key — The Bearer API key is missing, malformed, or unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The Bearer API key is missing, malformed, or unknown. type: invalid_request_error code: invalid_api_key Error_api_key_frozen: description: 403 api_key_frozen — The API key has been administratively frozen. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The API key has been administratively frozen. type: forbidden code: api_key_frozen Error_api_key_revoked: description: >- 401 api_key_revoked — The API key has been revoked and is no longer usable. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The API key has been revoked and is no longer usable. type: invalid_request_error code: api_key_revoked Error_model_restricted: description: >- 403 model_restricted — The requested model is not in the key's allowedModels list. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The requested model is not in the key's allowedModels list. type: forbidden code: model_restricted Error_bad_request: description: >- 400 bad_request — The request shape is invalid in a way that does not fit a more specific code. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: >- The request shape is invalid in a way that does not fit a more specific code. type: invalid_request_error code: bad_request Error_validation_failed: description: >- 422 validation_failed — Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: >- Request body failed Zod schema validation. Structured per-field reasons are in `error.issues[]`. type: invalid_request_error code: validation_failed Error_not_found: description: 404 not_found — The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The requested resource does not exist. type: not_found code: not_found Error_already_exists: description: >- 409 already_exists — A resource with the same unique identity already exists. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: A resource with the same unique identity already exists. type: conflict code: already_exists Error_conflict: description: >- 409 conflict — Concurrent modification detected; the client should retry with the latest version. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: >- Concurrent modification detected; the client should retry with the latest version. type: conflict code: conflict Error_insufficient_balance: description: >- 402 insufficient_balance — Account credits balance is below the requested amount. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: Account credits balance is below the requested amount. type: insufficient_quota code: insufficient_balance Error_spending_limit_reached: description: >- 429 spending_limit_reached — Per-key daily or monthly spending cap has been exhausted. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: Per-key daily or monthly spending cap has been exhausted. type: rate_limit_error code: spending_limit_reached Error_all_keys_exhausted: description: >- 502 all_keys_exhausted — No contributor key has remaining capacity for the routed model. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: No contributor key has remaining capacity for the routed model. type: server_error code: all_keys_exhausted Error_rate_limited: description: >- 429 rate_limited — Caller exceeded the rate-limit window for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: Caller exceeded the rate-limit window for this endpoint. type: rate_limit_error code: rate_limited Error_stream_interrupted: description: 500 stream_interrupted — The SSE stream aborted before completion. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: The SSE stream aborted before completion. type: server_error code: stream_interrupted Error_contract_error: description: >- 500 contract_error — An on-chain call reverted or could not be confirmed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: An on-chain call reverted or could not be confirmed. type: server_error code: contract_error Error_internal_error: description: 500 internal_error — Unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: Unexpected server-side failure. type: server_error code: internal_error Error_service_unavailable: description: >- 503 service_unavailable — A required dependency is down or misconfigured. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: message: A required dependency is down or misconfigured. type: server_error code: service_unavailable externalDocs: description: Inference guide, quickstarts, SDK matrix url: https://docs.compute.finance/inference-api