> ## Documentation Index > Fetch the complete documentation index at: https://runcrate.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Top up the balance > Adds credit by charging the workspace's saved default card (cards are added only in the dashboard). Needs an API key or agent sign-in with the billing permission, which a workspace owner or manager turns on in the dashboard's API keys page with daily and monthly caps (UTC; declined and cancelled top-ups do not count). Every outcome answers 200 with a `status`. The same `idempotency_key` answers the same top-up with its current status and the header `Idempotent-Replayed: true`, so re-send the request to read a `processing` or `requires_action` top-up; it never charges twice. ## OpenAPI ````yaml /api-reference/openapi.json post /billing/topups openapi: 3.1.0 info: title: Runcrate API version: 1.0.0 summary: OpenAI-compatible inference API + GPU infrastructure API. description: >- Runcrate exposes two API surfaces. The inference API at `https://api.runcrate.ai/v1` is OpenAI-compatible: it accepts the standard OpenAI SDK with the base URL changed. The infrastructure API at `https://www.runcrate.ai/api/v1` manages GPU instances, jobs, persistent volumes, environments, SSH keys, templates, and billing. Both share a single `rc_live_*` API key. Pricing is per-token, per-image, per-second, or per-minute on the inference API (varies by model; see https://www.runcrate.ai/api/models/catalog for live rates) and per-second on GPU rentals (see https://www.runcrate.ai/pricing for hourly rates per GPU class). All infrastructure API responses are wrapped in `{ "data": ... }`. List responses also include a `meta` object with pagination cursors. Error responses use `{ "error": { "code": "...", "message": "..." } }`. termsOfService: https://www.runcrate.ai/terms contact: name: Runcrate url: https://www.runcrate.ai/contact license: name: Proprietary url: https://www.runcrate.ai/terms servers: - url: https://api.runcrate.ai/v1 description: Inference API (OpenAI-compatible) - url: https://www.runcrate.ai/api/v1 description: >- Infrastructure API (instances, jobs, storage, environments, ssh-keys, templates, billing) security: - ApiKeyAuth: [] tags: - name: Chat description: OpenAI-compatible chat completions. - name: Messages description: Anthropic-compatible Messages API, for Claude Code and the Anthropic SDKs. - name: Responses description: >- OpenAI-compatible Responses API, for Codex and responses.create. Nothing is stored. - name: Images description: Text-to-image generation. - name: Videos description: Async text-to-video and image-to-video generation. - name: Audio description: Text-to-speech and speech-to-text. - name: Embeddings description: Vector embeddings for RAG and search. - name: Models description: Model catalog discovery. - name: Instances description: GPU instance lifecycle. - name: Jobs description: >- Run one command on its own GPU machine. The machine stops, and billing ends, when the command exits. - name: Schedules description: >- Start an instance or a job later: once at a set time, or on a repeating cron schedule in your timezone. - name: Clusters description: >- Multi-machine GPU clusters on a private network, with Slurm, Kubernetes or Ray, bought by the machine. All or nothing: every machine starts or none does, billed from when every machine is up. - name: Storage description: Persistent volume management. - name: Environments description: Resource isolation containers within a workspace. - name: Secrets description: >- Names of the secrets an environment's machines get. Values are set in the dashboard and never returned. - name: SSH Keys description: SSH key management for instance access. - name: Templates description: Pre-built instance images and configurations. - name: Billing description: >- Credit balance and runway, top-ups, auto-recharge, payment methods, transactions, usage metrics. - name: Model calls description: >- The log of calls to the inference API, kept 30 days: outcome, timing, tokens, cost, end user, session and tags. Never the prompt or the answer. paths: /billing/topups: servers: - url: https://www.runcrate.ai/api/v1 post: tags: - Billing summary: Top up the balance description: >- Adds credit by charging the workspace's saved default card (cards are added only in the dashboard). Needs an API key or agent sign-in with the billing permission, which a workspace owner or manager turns on in the dashboard's API keys page with daily and monthly caps (UTC; declined and cancelled top-ups do not count). Every outcome answers 200 with a `status`. The same `idempotency_key` answers the same top-up with its current status and the header `Idempotent-Replayed: true`, so re-send the request to read a `processing` or `requires_action` top-up; it never charges twice. operationId: createTopUp parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- May be sent instead of `idempotency_key` in the body; if both are sent they must match. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TopUpRequest' responses: '200': description: >- The top-up and its status. On a replay of an earlier key, its current status, with `Idempotent-Replayed: true`. headers: Idempotent-Replayed: description: '`true`: this answers an earlier request with the same key.' schema: type: string enum: - 'true' content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/TopUp' examples: succeeded: summary: Paid and credited value: data: id: 8d0c7b1e-3f2a-4e5b-9c8d-1a2b3c4d5e6f status: succeeded amount_usd: 50 idempotency_key: nightly-1 invoice_number: RC-000123 balance_usd: 104.12 created_at: '2026-10-26T10:00:00Z' requires_action: summary: Waiting for the card holder value: data: id: 8d0c7b1e-3f2a-4e5b-9c8d-1a2b3c4d5e6f status: requires_action amount_usd: 50 idempotency_key: nightly-1 invoice_number: RC-000123 confirm_url: >- https://www.runcrate.ai/dashboard/billing?action=confirm-top-up&workspace=a3c9e2f0-1b7d-4e55-8f20-6d4b9c1a7e33&invoice=c4e8a2f1-7b3d-4f60-9a15-2e8d0b6c3f71 expires_at: '2026-10-27T10:00:00Z' created_at: '2026-10-26T10:00:00Z' declined: summary: Declined, nothing charged value: data: id: 8d0c7b1e-3f2a-4e5b-9c8d-1a2b3c4d5e6f status: declined amount_usd: 50 idempotency_key: nightly-1 invoice_number: RC-000123 reason: card_declined message: >- Your card has insufficient funds. Nothing was charged. You can pay by bank transfer instead. created_at: '2026-10-26T10:00:00Z' '401': $ref: '#/components/responses/Unauthorized' '402': description: >- `TOPUP_CAP_REACHED`: the top-up would pass a cap; `details` has `cap` (`daily`, `monthly` or `new_workspace`), `cap_usd`, `spent_usd`, `remaining_usd` and `resets_at`. `NO_PAYMENT_METHOD`: the workspace has no saved default card. `PAYMENT_HOLD`: card payments are paused while a card dispute is open. Nothing was charged. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TOPUP_CAP_REACHED message: >- This top-up would pass this key's daily top-up cap of $250.00 ($225.00 used). Nothing was charged. An owner or manager can raise the cap on the API keys page. details: cap: daily cap_usd: 250 spent_usd: 225 remaining_usd: 25 resets_at: '2026-10-27T00:00:00Z' '403': description: >- `BILLING_PERMISSION_REQUIRED`: this key or sign-in does not have the billing permission. A workspace owner or manager turns it on in the dashboard's API keys page. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: BILLING_PERMISSION_REQUIRED message: >- This key or sign-in cannot top up. An owner or manager of the workspace turns the billing permission on for it on the API keys page, with its daily and monthly caps. '409': description: >- `IDEMPOTENCY_KEY_REUSED`: the key was used for a top-up of another amount; use a new key. `conflict`: a top-up with this key, or another card payment of the workspace, is being charged right now; re-send the same request after `Retry-After` seconds. headers: Retry-After: description: Seconds to wait before re-sending. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This idempotency_key was used for a $50.00 top-up. Use a new key for a new top-up. '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' components: schemas: TopUpRequest: type: object required: - amount_usd properties: amount_usd: type: number minimum: 20 maximum: 10000 description: 'Amount to add, in USD: 20 to 10,000, in dollars and cents.' example: 50 idempotency_key: type: string minLength: 1 maxLength: 255 pattern: ^[\x21-\x7e]+$ description: >- Names this top-up: 1 to 255 printable ASCII characters, no spaces (a UUID per top-up works). Required here unless sent as the `Idempotency-Key` header; if both are sent they must match. The same key answers the same top-up with its current status and never charges twice. example: nightly-1 TopUp: type: object required: - id - status - amount_usd - idempotency_key - invoice_number - created_at properties: id: type: string format: uuid example: 8d0c7b1e-3f2a-4e5b-9c8d-1a2b3c4d5e6f status: type: string enum: - succeeded - processing - requires_action - declined example: succeeded description: >- `succeeded`: paid and credited (`balance_usd`). `processing`: going through, not credited yet; re-send the same request to read it. `requires_action`: the bank wants the card holder to confirm; nothing is charged until a signed-in owner or manager opens `confirm_url` before `expires_at`. `declined`: nothing was charged (`reason`, `message`). amount_usd: type: number example: 50 idempotency_key: type: string example: nightly-1 invoice_number: type: string nullable: true example: RC-000123 balance_usd: type: number description: The balance after the top-up. Only when `status` is `succeeded`. example: 104.12 confirm_url: type: string format: uri description: >- The dashboard page where a workspace owner or manager, signed in, confirms the payment. Only when `status` is `requires_action`. example: >- https://www.runcrate.ai/dashboard/billing?action=confirm-top-up&workspace=a3c9e2f0-1b7d-4e55-8f20-6d4b9c1a7e33&invoice=c4e8a2f1-7b3d-4f60-9a15-2e8d0b6c3f71 expires_at: type: string format: date-time nullable: true description: >- When `confirm_url` stops working. Only when `status` is `requires_action`. example: '2026-10-27T10:00:00Z' reason: type: string enum: - card_declined - payment_blocked - authentication_required description: Why nothing was charged. Only when `status` is `declined`. example: card_declined message: type: string description: >- A sentence saying why, for a person. Only when `status` is `declined`. example: >- Your card has insufficient funds. Nothing was charged. You can pay by bank transfer instead. created_at: type: string format: date-time example: '2026-10-26T10:00:00Z' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- Machine-readable error code (e.g. `validation_error`, `unauthorized`, `not_found`, `insufficient_credits`, `rate_limited`, `internal_error`). message: type: string description: Human-readable error message. details: type: object additionalProperties: true description: Optional structured error context. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Request shape or values failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limited. Retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Use a Runcrate API key with the `rc_live_*` prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.