---
title: "Get an IC Key with IC Credits (instant at the ring default, queued above it)"
method: POST
path: "/api/credits/request"
tags: ["keys", "browser-session"]
---

# Get an IC Key with IC Credits (instant at the ring default, queued above it)

`POST /api/credits/request`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/credits/request`
- Auth: API key in cookie `__session`

Clerk-session only (NOT reachable with an agt_ bearer; agents use ic_credits_request). Applies the RING RULE: a member request at or under the ring default (operator $50, ic-member $20, ai-floor / ft-member $10 per month) MINTS on the spot and the plaintext + paste blocks come back ONCE in this response (`mode: minted`); above the default it queues for an operator (`mode: queued`); a member already holding a live key gets `mode: existing` with its usage (one key per member; regenerate instead). Workshop keys (any tier, event-tied, 5h + $5) and benchmark keys (operator) mint on the spot. Per-user rate-limited, FAILS CLOSED.

## Request body

- CreditsRequestRequest
  - `kind` 'workshop' | 'member' | 'benchmark', required: workshop = any signed-in user (walk-ins; 5h + $5, event-tied); member = ft-member and above (monthly budget); benchmark = operator only.
  - `event_id` string: Required for a workshop key: the upcoming event it is for (Luma URL or hackathon slug).
  - `event_title` string
  - `budget_usd` 5 | 10 | 20 | 50 | 100: Monthly budget of IC Credits in USD (member / benchmark). Default: the ring default (operator 50, ic-member 20, ai-floor / ft-member 10). At or under the default mints instantly; above it queues for an operator, who picks the applied figure.
  - `multiplier` number: LEGACY weekly-token multiplier (pre-2026-09-15). Accepted and ignored; use budget_usd.
  - `default_model` string: The catalog model id to pin as the key's default (the bundle's ANTHROPIC_MODEL). Ids with a / are metered in USD. Unknown id = 400. Omitted = the gateway's default.
  - `note` string: Free text recorded on the request.

## Response `200`

Minted (plaintext once), queued (request_id), or existing (usage).

- CreditsRequestResponse: Discriminated on `mode`. minted: the key exists now and `agent_token` + `bundle` are surfaced ONCE, here. queued: an operator approves; poll /api/credits/status?request_id and then POST /api/credits/pickup. existing: the member already holds a live member key (one per person); `usage` is its spend and POST /api/credits/regenerate is how to get a fresh key.
  - `ok` boolean, required
  - `mode` 'minted' | 'queued' | 'existing', required
  - `request_id` string: The request that minted or queued (absent on some `existing` answers).
  - `token_prefix` string: The key's prefix (minted / existing). Never the plaintext except in agent_token on a mint.
  - `agent_token` string: minted only: the plaintext key, surfaced EXACTLY ONCE.
  - `bundle` object: minted only: ready-to-paste Claude Code (copy_paste) and OpenAI-compatible (copy_paste_openai) configuration.
  - `proxy` object: minted only: the key's limits block (kind, models, default_model, budget, expiry). No secret.
  - `status` 'pending': queued only.
  - `budget_usd` number: queued only: the budget the request asks for.
  - `usage` CreditsStatus: The member's IC Credits console state.
    - `has_key` boolean, required: Whether a live member key exists.
    - `token_prefix` string
    - `kind` string
    - `budget_usd` number, nullable
    - `budget_used_usd` number
    - `budget_remaining_usd` number, nullable
    - `budget_period` 'month' | 'lifetime' | 'null', nullable
    - `budget_resets` string, nullable
    - `by_model` object[]
      - `model` string
      - `provider` string
      - `tokens` integer
    - `default_model` string
    - `pending_request` object: A member request waiting for an operator, when one exists.
      - `request_id` string
      - `budget_usd` number
      - `created_at` string, date-time

## Other responses

- `400`: Invalid JSON, unknown kind, bad budget_usd / default_model, or a missing event_id.
- `401`: Not signed in.
- `403`: Tier floor for the requested kind not met (member below ft-member, benchmark below operator).
- `429`: Per-user request cap reached (carries `limit` + `retry_after_seconds`; a mint counts as a request).
- `500`: Auth check failed or the mint failed.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)