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)
| Route | Method | Purpose | Pathway |
|---|---|---|---|
/v1/ai/models | GET | Model catalog | — |
/v1/ai/stream | POST | Downcity Model Protocol stream transport | CityModel |
/v1/ai/image/create | POST | Create image generation job | SDK |
/v1/ai/image/result | POST | Poll image generation job | SDK |
/v1/ai/video | POST | Video generation | SDK |
/v1/ai/tts | POST | Text-to-speech | SDK |
/v1/ai/asr | POST | Speech recognition | SDK |
/v1/ai/decision | POST | Structured decision (System One) | SDK |
/v1/ai/chat/completions | POST | OpenAI-compatible endpoint | OpenAI |
/v1/accounts/login/start | POST | Specify client_type; receive login_id, login_secret, and the next step | — |
/v1/accounts/login/continue | POST | Submit input with login_id and login_secret | — |
/v1/accounts/login/result | POST | Query status with the claim proof; never returns a token | — |
/v1/accounts/login/exchange | POST | Exchange the claim proof and stable exchange_id for device session credentials | — |
/v1/accounts/refresh | POST | Rotate refresh credentials with a persisted refresh_id | — |
/v1/accounts/logout | POST | Revoke a device session using refresh credentials or a valid Bearer token | — |
/v1/federation/token | GET | Validate the current Bearer User Token online | — |
/v1/accounts/me | GET | Read the authenticated current user | — |
/v1/accounts/oauth/callback | GET | Third-party OAuth callback entry | — |
/v1/services | GET | Registered service list | — |
/v1/{service}/{action} | POST | Generic 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)
| Route | Method | Purpose |
|---|---|---|
/v1/accounts/tokens/issue | POST | Issue user_token |
/v1/env/list | GET | View runtime env |
/v1/env/upsert | POST | Write env variable |
/v1/env/remove | POST | Delete env variable |
/v1/env/import | POST | Bulk import .env |
Auth Header
Authorization: Bearer <user_token>
Content-Type: application/jsonAction 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 failure | HTTP status | code |
|---|---|---|
| Invalid JSON syntax | 400 | INVALID_JSON |
A JSON array, null, string, number, or boolean | 400 | INVALID_INPUT |
| Request body cannot be read | 400 | INVALID_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.
| Category | Exact paths | max_body_bytes | body_timeout_ms | execution_timeout_ms |
|---|---|---|---|---|
ordinary | All other paths, including /v1/ai/image/result | 1,048,576 (1 MiB) | 15,000 | 30,000 |
webhook | /v1/payment/webhook | 2,097,152 (2 MiB) | 15,000 | 30,000 |
model_stream | /v1/ai/stream | 41,943,040 (40 MiB) | 60,000 | 180,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,000 | 180,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 failure | HTTP status | code |
|---|---|---|
Invalid Content-Length, not a non-negative decimal integer | 400 | INVALID_CONTENT_LENGTH |
Unreadable body or a chunk that is not a Uint8Array | 400 | INVALID_BODY |
| Body read deadline reached | 408 | REQUEST_BODY_TIMEOUT |
| Declared length or actual body exceeds the limit | 413 | BODY_TOO_LARGE |
Unsupported Content-Encoding | 415 | UNSUPPORTED_CONTENT_ENCODING |
| Client cancellation | 499 | REQUEST_CANCELLED |
| Execution deadline reached before the response starts | 504 | REQUEST_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 phase | timeout_phase | retryable |
|---|---|---|
| Response-stream establishment, not TCP connection | connect | true |
| First useful output | first_output | true |
| Stalled output | idle | false |
| Total execution | total | false |
| Agent step recovery budget | recovery_budget | false |
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 status | type | Default code |
|---|---|---|
| 400 | invalid_request_error | INVALID_REQUEST |
| 401 | authentication_error | UNAUTHENTICATED |
| 403 | permission_error | FORBIDDEN |
| 404 | not_found_error | NOT_FOUND |
| 408 | invalid_request_error | REQUEST_BODY_TIMEOUT |
| 409 | conflict_error | CONFLICT |
| 413 | invalid_request_error | BODY_TOO_LARGE |
| 415 | invalid_request_error | UNSUPPORTED_CONTENT_ENCODING |
| 429 | rate_limit_error | RATE_LIMITED |
| 499 | request_cancelled_error | REQUEST_CANCELLED |
| Other 4xx | invalid_request_error | REQUEST_REJECTED |
| 503 | server_error | SERVICE_UNAVAILABLE |
| 504 | server_error | REQUEST_TIMEOUT |
| Other 5xx | server_error | INTERNAL_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",
});