HTTP API

Auth, requests, and responses under the unified `/v1/*` route space.

All actions are exposed through the same shape:

POST /v1/{service}/{action}
GET  /v1/{service}/{action}

The bearer credential decides the request identity:

  • no token: guest
  • user_token: user
  • administrator session token: admin

Each action declares which identities it allows. The default is ["user"]; [] means guest access is allowed.

City Routes (common user-side routes)

RouteMethodPurposePathway
/v1/ai/modelsGETModel catalog—
/v1/ai/streamPOSTDowncity Model Protocol stream transportCityModel
/v1/ai/image/createPOSTCreate image generation jobSDK
/v1/ai/image/resultPOSTPoll image generation jobSDK
/v1/ai/videoPOSTVideo generationSDK
/v1/ai/ttsPOSTText-to-speechSDK
/v1/ai/asrPOSTSpeech recognitionSDK
/v1/ai/decisionPOSTStructured decision (System One)SDK
/v1/ai/chat/completionsPOSTOpenAI-compatible endpointOpenAI
/v1/accounts/login/startPOSTSpecify client_type; receive login_id, login_secret, and the next step—
/v1/accounts/login/continuePOSTSubmit input with login_id and login_secret—
/v1/accounts/login/resultPOSTQuery status with the claim proof; never returns a token—
/v1/accounts/login/exchangePOSTExchange the claim proof and stable exchange_id for device session credentials—
/v1/accounts/refreshPOSTRotate refresh credentials with a persisted refresh_id—
/v1/accounts/logoutPOSTRevoke a device session using refresh credentials or a valid Bearer token—
/v1/federation/tokenGETValidate the current Bearer User Token online—
/v1/accounts/meGETRead the authenticated current user—
/v1/accounts/oauth/callbackGETThird-party OAuth callback entry—
/v1/servicesGETRegistered service list—
/v1/{service}/{action}POSTGeneric action call—

/v1/accounts/oauth/callback is the fixed return URL for GitHub, Google, and other third-party OAuth providers. Product clients usually do not call it directly.

OAuth supplies client_type, an exact redirect_uri, random state, and S256 PKCE. Website callbacks must match AccountsService trusted_web_callbacks; an empty list rejects web OAuth. CLI/Desktop use an exclusive local 127.0.0.1 ephemeral port. After validating callback state, exchange the authorization code, private verifier, login_secret, and stable exchange_id for a token. Status never delivers credentials.

Federation validates signature, issuer, audience, expiry, and session revocation for protected requests. Device logout revokes its entire session. SDK logout preserves credentials on transport failure; Desktop and CLI end local use before attempting remote revocation. Running streams are not forcibly interrupted.

Admin Routes (same route space, admin credential required)

RouteMethodPurpose
/v1/accounts/tokens/issuePOSTIssue user_token
/v1/env/listGETView runtime env
/v1/env/upsertPOSTWrite env variable
/v1/env/removePOSTDelete env variable
/v1/env/importPOSTBulk import .env

Auth Header

Authorization: Bearer <user_token>
Content-Type: application/json

Action request bodies

POST Actions default to body: "json". An empty or whitespace-only body becomes {}; any non-empty body must be a JSON object. GET Actions read input from query parameters.

Input failureHTTP statuscode
Invalid JSON syntax400INVALID_JSON
A JSON array, null, string, number, or boolean400INVALID_INPUT
Request body cannot be read400INVALID_BODY

Webhook Actions can explicitly select body: "raw". The Action Context's raw_body and an Installable Action's ctx.text() preserve the original text. The latter's ctx.json() still requires a JSON object when called, with empty or whitespace-only input becoming {}. Service.action() accepts optional options.body; Installable ctx.route() accepts optional body only for Action routes. See Service and Action.

Native handler: { request } route bodies also undergo one bounded read at the HTTP boundary. The Request is then rebuilt from the original bytes without Action JSON parsing. OAuth form submissions, callbacks, and redirects use their native protocols.

HTTP boundary and default limits

Federation.fetch() enables bounded body reading before middleware and the Router by default. The following policies match exact paths; 1 MiB is 1,048,576 bytes.

CategoryExact pathsmax_body_bytesbody_timeout_msexecution_timeout_ms
ordinaryAll other paths, including /v1/ai/image/result1,048,576 (1 MiB)15,00030,000
webhook/v1/payment/webhook2,097,152 (2 MiB)15,00030,000
model_stream/v1/ai/stream41,943,040 (40 MiB)60,000180,000
media/v1/chat/completions, /v1/ai/chat/completions, and image/create, asr, tts, embedding, rerank, video, audio, decision under /v1/ai/41,943,040 (40 MiB)60,000180,000

The boundary adds up the actual byteLength of each Uint8Array chunk, including JSON, Base64, and other wrapping bytes. Missing Content-Length, chunked transfer, or a falsely small declared length cannot bypass the limit. A declared length over the limit can be rejected early. The body deadline covers the entire read and does not reset on new chunks. Content-Encoding must be absent or identity; other encodings are not decompressed.

HTTP boundary failureHTTP statuscode
Invalid Content-Length, not a non-negative decimal integer400INVALID_CONTENT_LENGTH
Unreadable body or a chunk that is not a Uint8Array400INVALID_BODY
Body read deadline reached408REQUEST_BODY_TIMEOUT
Declared length or actual body exceeds the limit413BODY_TOO_LARGE
Unsupported Content-Encoding415UNSUPPORTED_CONTENT_ENCODING
Client cancellation499REQUEST_CANCELLED
Execution deadline reached before the response starts504REQUEST_TIMEOUT

The execution deadline starts when the request body has been fully read and covers middleware and business handling. For non-SSE responses, the timer stays active until the response body finishes reading or is cancelled. Expiry before headers returns 504 REQUEST_TIMEOUT; after headers have been sent, it only ends the stream without changing the HTTP status. Bodyless OPTIONS requests also use the ordinary execution deadline. Model and media endpoints wait up to 180 seconds for response headers by default; this is not a first useful output deadline.

On receiving an SSE Response, the HTTP timer switches to the stream_lifetime_ms total deadline, defaulting to 900_000 (15 minutes). It is measured from the end of request body reading and includes the wait for response headers, without buffering SSE. The model total deadline also defaults to 15 minutes but starts at provider execution. These clocks are independent; whichever expires first applies. Synchronous JSON remains subject to the default 180-second HTTP execution deadline, and shorter provider deadlines still apply.

After headers have been sent, the HTTP boundary does not change the status or synthesize generic SSE error frames. Cancellation or timeout aborts downstream work, cancels the reader, and ends the stream. Completion or cancellation releases timers, listeners, and readers without waiting for an upstream cancel that could hang indefinitely.

Language model deadlines and errors

Native /v1/ai/stream, OpenAI-compatible SSE and JSON, and every Relay language model execution share the server-side AIServiceOptions.model_stream?: Partial<AIModelStreamPolicy>: connect_timeout_ms: 120_000, first_output_timeout_ms: 120_000, idle_timeout_ms: 120_000, and total_timeout_ms: 900_000. Clients cannot raise these limits through a request. The first-output budget accumulates provider open and actual read waits before useful output; idle accumulates actual read waits between useful outputs. Backpressure does not consume either budget, while total wall-clock timing continues. See Calling models for useful events and configuration examples.

Timeout phasetimeout_phaseretryable
Response-stream establishment, not TCP connectionconnecttrue
First useful outputfirst_outputtrue
Stalled outputidlefalse
Total executiontotalfalse
Agent step recovery budgetrecovery_budgetfalse

Model timeouts use code: "provider_timeout" and status_code: 504. The safe message is Model provider timed out, or Model recovery budget exhausted for recovery budget expiry. Before response start, a timeout returns HTTP 504; an already-started native stream emits model_error without changing its HTTP status. If needed, a framework model_start precedes the failure terminal without fabricating usage. OpenAI SSE sends an error frame without a success [DONE]; JSON aggregation returns 504. retryable describes a transient failure, not unconditional permission to resend: Agent also checks partial output, cancellation, attempts, and its 900-second recovery budget. Retry-After propagates as an absolute Unix millisecond retry_at_ms deadline. Direct stream calls do not automatically retry.

Trustworthy usage facts are retained. Missing usage does not lead to estimated tokens or costs. Existing bill callbacks use actual facts; business charging rules do not promise zero charges in every case without usage. completion.outcome distinguishes succeeded, failed, and cancelled. A cancel after the terminal event does not change the outcome or cause duplicate settlement or charges.

499 REQUEST_CANCELLED represents client cancellation; a disconnected client is not guaranteed to receive a response. Handlers can read Action Context.abort_signal, ServiceRouteContext.abort_signal, or the native request.signal. Adapters should combine the request signal with their own deadlines; shorter upstream deadlines still apply. Cancellation is cooperative: database operations may continue, transactions are not automatically rolled back, and no automatic retry is triggered. Queued image tasks run independently and do not inherit cancellation from foreground creation or result queries.

See Federation runtime for configuration and exact-path overrides. Edge / local-node link the SDK through workspace dependencies, so development builds use this default policy. Production deployment requires building the SDK and service artifacts containing the feature; running instances do not update automatically.

Request IDs

Every request entering the Federation.fetch() HTTP boundary receives a server-generated req_<UUID> before middleware runs. Caller-supplied request IDs are ignored. Boundary responses within the ordinary HTTP protocol overwrite x-request-id, including middleware short circuits, 413, 408, 504, success, business errors, native Responses, streams, and route 404s. The Router, Action Context's request_id and locals.request_id, and AI relay share the same ID. Responses handled by the host outside this boundary are outside this scope; HTTP 101 upgrades are neither rewrapped nor managed, and their x-request-id response header is not guaranteed.

Framework errors

Errors thrown and caught by the framework use this JSON shape:

{
  "error": {
    "code": "INVALID_JSON",
    "message": "INVALID_JSON: Request body must be valid JSON",
    "type": "invalid_request_error",
    "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

An explicit integer statusCode from 400 through 599 determines the HTTP status. With that valid status, a code matching ^[A-Za-z][A-Za-z0-9_]{0,63}$ is preserved, including domain codes such as 503 async_dispatch_unavailable. Missing or invalid codes use the defaults below. Missing or invalid statusCode always becomes 500 INTERNAL_ERROR, even when a code is present. type is determined by status.

HTTP statustypeDefault code
400invalid_request_errorINVALID_REQUEST
401authentication_errorUNAUTHENTICATED
403permission_errorFORBIDDEN
404not_found_errorNOT_FOUND
408invalid_request_errorREQUEST_BODY_TIMEOUT
409conflict_errorCONFLICT
413invalid_request_errorBODY_TOO_LARGE
415invalid_request_errorUNSUPPORTED_CONTENT_ENCODING
429rate_limit_errorRATE_LIMITED
499request_cancelled_errorREQUEST_CANCELLED
Other 4xxinvalid_request_errorREQUEST_REJECTED
503server_errorSERVICE_UNAVAILABLE
504server_errorREQUEST_TIMEOUT
Other 5xxserver_errorINTERNAL_ERROR

Explicit 4xx httpError messages are preserved. Every 5xx response, including errors with preserved domain codes, hides the original message: 503 uses Service temporarily unavailable, 504 uses Request timed out, and other 5xx statuses use Internal server error. Unknown Errors use the generic 500 response.

Business and native handlers own the error bodies of Responses they return directly. The framework does not normalize those bodies; it still overwrites x-request-id. Adding that header neither consumes the body nor buffers SSE. After streaming starts, boundary timeout or cancellation aborts downstream work and cancels the reader. The response cannot switch HTTP status or become a JSON error, and the boundary does not synthesize generic SSE error frames. An onError hook failure does not replace the original error.

Framework 5xx structured logs contain only event, request_id, status, and code. They exclude request/response bodies, tokens, the original Error, and stack traces. This is not a complete access log and does not retain original stacks.

GET /v1/ai/models

The same route returns different visibility by identity:

  • with user_token: only currently callable models
  • with an administrator session token: the full code-registered model list plus env_requirements
{ "items": [
  { "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash",
    "description": "...", "modalities": ["text","stream"],
    "tags": ["deepseek"],
    "price": ["Input: 1 credit / 1K tokens", "Output: 3 credits / 1K tokens"],
    "meta": {},
    "reasoning": {
      "efforts": [
        { "id": "low", "name": "Low" },
        { "id": "high", "name": "High" }
      ],
      "default_effort": "low"
    } }
]}
{ "items": [
  { "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash",
    "description": "", "modalities": ["text","stream","openai"],
    "tags": ["deepseek"],
    "price": ["Input: 1 credit / 1K tokens", "Output: 3 credits / 1K tokens"],
    "meta": {},
    "env_requirements": [
      { "key": "DEEPSEEK_API_KEY", "description": "deepseek API Key", "required": true }
    ] }
]}

User sessions own identity, permissions, and Credits. City automatically carries optional city_id for logs, usage, and job source only. Business calls use federation.user.service(name) on the current Federation; administrators use a separate Session.

GET /v1/services

{
  "items": [
    { "id": "ai", "name": "AI", "env": [] },
    { "id": "accounts", "name": "Accounts", "env": [] }
  ]
}

env exposes the runtime env requirements declared by the service so admin or debugging surfaces can render dependencies.

POST /v1/ai/stream

This versioned Downcity Model Protocol transport accepts { protocol_version: 1, model_id, call }, where call is a ModelCall containing messages, tools, reasoning, and generation options. SSE returns { protocol_version: 1, event: ModelStreamEvent }. Product code should use the CityModel returned by the catalog or call city.ai.stream({ model, call }). Both paths consume the same standard event stream.

When supplied, call.reasoning.effort must match the final model catalog's reasoning.efforts. AIService validates it again after fallback selects the execution model.

POST /v1/ai/decision

Structured decision transport. Accepts { model, state, questions } where state is { type: "text", text } or { type: "json", data }, and returns { answers, usage? }. Each answer carries value, an optional probability, and a distribution for choice questions.

Requests are validated before execution: question ids must be unique, choice questions require 1 to 255 unique options, and score requires min < max. Invalid input fails with 422 without recording usage.

Product code should call city.ai.decision({ model, state, questions }).

POST /v1/ai/chat/completions

OpenAI-compatible endpoint. Accepts standard { model, messages, stream } format.

Non-streaming returns OpenAI chat.completion JSON. Streaming returns OpenAI SSE.

Fully compatible with OpenAI SDK:

const openai = new OpenAI({
  baseURL: "http://127.0.0.1:43127/v1/ai",
  apiKey: "ub_xxx",
});