HTTP API

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/text`	`POST`	Text generation	SDK
`/v1/ai/stream`	`POST`	CityModel LanguageModelV3 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/chat/completions`	`POST`	OpenAI-compatible endpoint	OpenAI
`/v1/accounts/login/start`	`POST`	Create a login attempt; returns input, redirect, or done	—
`/v1/accounts/login/continue`	`POST`	Submit an input login step	—
`/v1/accounts/login/result`	`GET`	Read the login result and `user_token`	—
`/v1/accounts/me`	`GET`	Read the current user and its verified Bureau	—
`/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.

Admin Routes (same route space, admin credential required)

Route	Method	Purpose
`/v1/bureaus/list`	`GET`	List Bureaus
`/v1/bureaus/create`	`POST`	Create a Bureau with required `server_url`
`/v1/bureaus/pause`	`POST`	Pause a Bureau
`/v1/bureaus/activate`	`POST`	Activate a Bureau
`/v1/bureaus/archive`	`POST`	Archive a Bureau
`/v1/bureaus/server/update`	`POST`	Update the Bureau's single Server entrypoint
`/v1/bureaus/current`	`GET`	Resolve the current Bureau from a User Token
`/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/json

`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 }
    ] }
]}

`POST /v1/ai/text`

Request:

{ "model": "deepseek-v4-flash", "prompt": "Hello", "reasoning_effort": "high" }

reasoning_effort is optional, but when present it must match an ID from the model catalog's reasoning.efforts. If model fallback changes the execution model, AIService validates the level against that final model.

Response:

{ "id": "msg_xxx", "role": "assistant", "parts": [{ "type": "text", "text": "Hi!" }] }

Federation resolves both the user and Bureau identity from the bearer user_token. The request body does not participate in identity resolution.

`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 LanguageModelV3 transport is internal to CityModel. It carries standard model prompts, function tools, reasoning, usage, and finish reasons as SSE events. Product code should use the CityModel returned by the model catalog instead of constructing transport requests manually. city.ai.stream() uses the same transport and converts model parts into UIMessageChunk objects in the SDK.

`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",
});

Table of Contents