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.

Agents read the same account card through the MCP server tool account_get (read-only; the key reference, tokens and billing ids are stripped). profile_get returns only the profile part (name, username, consents, referral handle), profile_update sets the username (consents, training opt-out and referral codes stay in the apps) and feedback_submit rates one of your own turns, like POST /v1/feedback.

GET

/v1/account

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Response Body

The account view.

application/json

response

Full account card returned by GET /v1/account.

wallet*|null

promo*|null

referral*|null

user_id*string

Formatuuid

email*string

Formatemail

training_opt_out*boolean

GDPR training flag. true means NOT consented (the default).

consents*array<>

user*

key*

plan*

usage*

referral_redeem_until*|

Until when a referral_code can still be redeemed (7 days after signup); null once closed.

Formatdate-time

features*

billing_url*"https://codai.ro/api/mobile/billing"

Formaturi

Value in"https://codai.ro/api/mobile/billing"

Example Request

curl -X GET 'https://ai.codai.ro/v1/account'

Example Request

curl -X GET 'https://ai.codai.ro/v1/account'

Example ResponseSchema

{
  "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": "user@example.com",
  "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": "user@example.com",
    "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"
}

{  "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": "user@example.com",  "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": "user@example.com",    "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"}

PATCH

/v1/account

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

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

application/json

body

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

The updated account (subset of the GET view plus the outcome fields).

application/json

response

Returned by PATCH /v1/account.

wallet*|null

promo*|null

referral*|null

user_id*string

Formatuuid

email*string

Formatemail

training_opt_out*boolean

consents*array<>

username_error*|

Why username was not applied; null when not sent or applied.

Value in"invalid""taken""change_limit"null

referral_result*|

Outcome of referral_code; null when not sent.

Value in"window_closed""none""invalid_code""self""already_referred""flagged""pending_payment""granted""cap_reached"null

Example Request

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

Example Request

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

Example ResponseSchema

{
  "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": "user@example.com",
  "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"
}

{  "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": "user@example.com",  "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"}

GET

/v1/receipt

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

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

Response Body

The aggregated receipt.

application/json

response

Aggregated usage for the caller. Micro-USD fields are integers; only cost_usd is converted.

events*integer

Number of usage events in scope.

tasks*integer

SUM of task-start markers (a count, not rows).

cost_micro_usd_total*integer

Total cost in USD micros.

cost_usd*number

cost_micro_usd_total / 1_000_000.

prompt_tokens*integer

completion_tokens*integer

cached_read_tokens*integer

cache_write_tokens*integer

by_upstream*array<>

Per upstream model, ordered by cost descending.

window*

Example Request

curl -X GET 'https://ai.codai.ro/v1/receipt'

Example Request

curl -X GET 'https://ai.codai.ro/v1/receipt'

Example ResponseSchema

{
  "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"
  }
}

{  "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"  }}

POST

/v1/feedback

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

Rating plus exactly one of event_id, session_id, client_request_id.

application/json

body

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 in1-1

comment?string

Lengthlength <= 500

Response Body

Rating stored (or updated).

application/json

response

ok*true

Value intrue

event_id*string

The usage event that was rated (resolved id when an alias was used).

Formatuuid

Example Request

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

Example Request

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

Example ResponseSchema

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

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

GET

/v1/phone/models

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Response Body

The signed catalog.

application/json

response

models*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/phone/models'

Example Request

curl -X GET 'https://ai.codai.ro/v1/phone/models'

Example ResponseSchema

{
  "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"
    }
  ]
}

{  "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"    }  ]}

Account

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Header Parameters

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Response Body