Account

Your account card, consents, cost receipts, turn feedback and the on-device model catalog.

GET /v1/receipt is the cost endpoint: pass session_id for one conversation or since for a window and read cost_micro_usd — USD micros, never converted. Training consent is opt-in (training_opt_out defaults to true). Pricing context: limits & pricing.

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

`application/json`

curl -X GET "https://example.com/v1/account"

{  "wallet": {    "balance_eur": 12.5,    "next_expiry_at": "2019-08-24T14:15:22Z",    "promo_granted_eur": 0,    "promo_cap_eur": 0,    "history": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "delta_eur": 10,        "source": "welcome_grant",        "expires_at": "2019-08-24T14:15:22Z",        "promo": "string",        "multiplier": 0,        "list_eur": 0,        "note": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ]  },  "promo": {    "slug": "launch-50",    "title": "string",    "banner_en": "string",    "banner_ro": "string",    "multiplier": 0.5,    "ends_at": "2019-08-24T14:15:22Z"  },  "referral": {    "username": "string",    "consented": true,    "share_url": "https://codai.ro/r/dragos_v",    "invited": 0,    "rewarded": 0,    "pending": 0,    "flagged": 0,    "earned_eur": 0,    "month_remaining": 0,    "lifetime_remaining": 0,    "reward_eur": 0,    "referee_reward_eur": 0,    "qualify_spend_eur": 0  },  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "email": "[email protected]",  "training_opt_out": true,  "consents": [    {      "surface": "desktop",      "terms_version": "1.1",      "privacy_version": "training-consent-v2-2026-09",      "accepted_at": "2026-09-20T09:15:00.000Z"    }  ],  "user": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "[email protected]",    "name": "string",    "username": "string",    "suggested_username": "string"  },  "key": {    "id": "string",    "app_id": "affd1d10-9538-4fc8-9e0b-4594a28c1335"  },  "plan": {    "tier": "pro",    "status": "active",    "current_period_end": "2019-08-24T14:15:22Z",    "cancel_at_period_end": true,    "has_billing_account": true,    "max_routing_tier": "small"  },  "usage": {    "tasks_today": 0,    "tasks_per_day": 0,    "tasks_month": 0,    "tasks_per_month": 0,    "budget_eur_per_day": 0,    "budget_eur_per_month": 0,    "credits": 0  },  "referral_redeem_until": "2019-08-24T14:15:22Z",  "features": {    "byok": true,    "subagents": true,    "persistent_memory": true,    "limits_exempt": true  },  "billing_url": "https://codai.ro/api/mobile/billing"}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-device*string

Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.

Formatuuid

Request Body

application/json

At least one field is required; unknown keys are rejected.

TypeScript Definitions

Use the request body type in TypeScript.

Strict object — unknown keys are rejected and at least one field must be present.

Properties1 <= properties

training_opt_out?boolean

true = do NOT use my data for training; false only via an explicit consent action.

consents?

Accepted terms/privacy versions for one client surface.

username?string

Normalised to [a-z0-9_]; changeable once. Outcome in username_error.

Length3 <= length <= 20

referral_consent?boolean

Opt in/out of the referral programme.

referral_code?string

Referrer's username. Redeemable within 7 days of signup; grants the referee reward.

Length3 <= length <= 20

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/account" \  -H "x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "wallet": {    "balance_eur": 12.5,    "next_expiry_at": "2019-08-24T14:15:22Z",    "promo_granted_eur": 0,    "promo_cap_eur": 0,    "history": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "delta_eur": 10,        "source": "welcome_grant",        "expires_at": "2019-08-24T14:15:22Z",        "promo": "string",        "multiplier": 0,        "list_eur": 0,        "note": "string",        "created_at": "2019-08-24T14:15:22Z"      }    ]  },  "promo": {    "slug": "launch-50",    "title": "string",    "banner_en": "string",    "banner_ro": "string",    "multiplier": 0.5,    "ends_at": "2019-08-24T14:15:22Z"  },  "referral": {    "username": "string",    "consented": true,    "share_url": "https://codai.ro/r/dragos_v",    "invited": 0,    "rewarded": 0,    "pending": 0,    "flagged": 0,    "earned_eur": 0,    "month_remaining": 0,    "lifetime_remaining": 0,    "reward_eur": 0,    "referee_reward_eur": 0,    "qualify_spend_eur": 0  },  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "email": "[email protected]",  "training_opt_out": true,  "consents": [    {      "surface": "desktop",      "terms_version": "1.1",      "privacy_version": "training-consent-v2-2026-09",      "accepted_at": "2026-09-20T09:15:00.000Z"    }  ],  "username_error": "invalid",  "referral_result": "window_closed"}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Query Parameters

session_id?string

Session to scope to (matches session_id or the derived session key). Takes precedence over since.

since?string

ISO 8601 lower bound on started_at. Ignored when session_id is given. Default is 24h ago. Unparseable → 400.

Formatdate-time

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

`application/json`

curl -X GET "https://example.com/v1/receipt"

{  "events": 0,  "tasks": 0,  "cost_micro_usd_total": 1834210,  "cost_usd": 1.83421,  "prompt_tokens": 0,  "completion_tokens": 0,  "cached_read_tokens": 0,  "cache_write_tokens": 0,  "by_upstream": [    {      "upstream_model": "claude-sonnet-4-5",      "events": 0,      "cost_micro_usd": 0    }  ],  "window": {    "from": "2019-08-24T14:15:22Z",    "to": "2019-08-24T14:15:22Z",    "session_id": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

Rating plus exactly one of event_id, session_id, client_request_id.

TypeScript Definitions

Use the request body type in TypeScript.

A rating plus one target. Zod rejects the body when none of the three targets is present.

event_id*string

Exact usage event id from the x-codai-event-id response header.

Formatuuid

session_id?string

Grade the caller's latest depth-0 turn in this session.

Length1 <= length <= 256

client_request_id?string

Grade the caller's latest depth-0 turn sent with this x-request-id.

Length1 <= length <= 256

rating?integer

Value in

1
-1

comment?string

Lengthlength <= 500

Response Body

`application/json`

curl -X POST "https://example.com/v1/feedback" \  -H "Content-Type: application/json" \  -d '{    "rating": 1  }'

{  "ok": true,  "event_id": "3f0b2c9e-1d4a-4b8c-9e7f-2a6d5c4b3a10"}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

`application/json`

curl -X GET "https://example.com/v1/phone/models"

{  "models": [    {      "id": "codai-nano-1b-q8",      "name": "string",      "file": "codai-nano-1b-q8.litertlm",      "sizeBytes": 3700000000,      "sha256": "string",      "backends": [        "cpu",        "gpu"      ],      "base": "string",      "notes": "string",      "url": "http://example.com",      "expiresAt": "2019-08-24T14:15:22Z"    }  ]}

200application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

200application/json

400application/json

401application/json

200application/json

400application/json

401application/json

403application/json

404application/json

200application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`