Session API

Xiaohe Agent exposes a REST Session API for programmatic agent workflows. It drives real CLI backends — Claude, Kimi, Codex, Cursor — and it is not a separate agent SDK.

Start a local control plane with the OS service lifecycle commands:

xiaohe server ensure    # install + start + write a desktop key when missing
xiaohe server install   # unit only
xiaohe server start

The default local base is http://127.0.0.1:8110. A hosted Session uses the address and key your operator gives you, and it may sit on a private network rather than the open internet. For what each window expects, see Quickstart.

Authentication

When authentication is enabled, every /v1/* request except health and the public UI paths needs a Bearer token:

Authorization: Bearer <api-key|access-jwt>

Issue and manage keys on the control-plane host:

xiaohe server pair        # mint a key and print it; --write-client (default) fills the desktop app
xiaohe keys issue --tenant local --label mac
xiaohe keys list
xiaohe keys revoke <id|prefix>

EventSource and SSE cannot send headers, so append the key as a query parameter there:

GET /v1/sessions/{id}/events?access_token=<key>&after=0&follow=true

Core endpoints

Method	Path	Purpose
POST	/v1/sessions	Create a hosted session
GET	/v1/sessions/{id}	Session status
POST	/v1/sessions/{id}/messages	Send a user message
GET	/v1/sessions/{id}/events	SSE event stream
POST	/v1/sessions/{id}/approvals	Approve or reject a pending action
POST	/v1/sessions/{id}/cancel	Cancel an in-flight reply
DELETE	/v1/sessions/{id}	End a session
GET	/v1/me	Caller identity and workspace hints
GET/PUT	/v1/provider	List or switch the Claude LLM provider
GET/PUT	/v1/voice/provider	List or switch the TTS/STT provider

Creating a session

POST /v1/sessions

{
  "tenant_id": "demo",
  "backend": "claude",
  "skill_ids": ["demo.echo"],
  "message": "optional first turn",
  "workspace_path": "/absolute/path/to/project",
  "persistent": false
}

• backend — claude (the default), kimi, codex, cursor, or fake for local testing. Sessions proxy the real CLIs; claude uses the Agent SDK with token streaming and --resume across turns.
• workspace_path — the caller's absolute project path, used as the working directory. Omit it for a sandboxed workspace.
• persistent — keep a long-lived host process for the session instead of one process per turn.
• skill_ids — restrict which product skills the session may load.

Messages and events

Send turns with POST /v1/sessions/{id}/messages:

{"content": "Hello"}

Progress arrives over SSE. Reconnect with after=<last_event_seq> to resume:

GET /v1/sessions/{id}/events?after=0&follow=true

Attachments

Upload files up to 50 MiB:

• POST /v1/sessions/{id}/attachments — multipart field file, returns {id, name, mime, size, kind}
• GET /v1/sessions/{id}/attachments — list metadata
• GET /v1/sessions/{id}/attachments/{att_id} — download bytes

Inbound attachments are appended to the prompt as local paths, which the agent's Read and image tools pick up.

Transcript

GET /v1/sessions/{id}/messages returns stable chat bubbles and is the source of truth when a UI reopens. Paging is optional and newest-first: limit (1–500) with a before_created_at plus before_msg_id keyset cursor. Omit limit for the full transcript.

Approvals

POST /v1/sessions/{id}/approvals

{"approval_id": "...", "approved": true, "note": ""}

When the agent needs a decision, the session enters waiting_approval and emits an approval_required event on the SSE stream.

Workspaces

• GET /v1/me — a suggested workspace_path for the caller
• GET /v1/workspaces — registered workspaces for the key's tenant
• POST /v1/workspaces — ensure or register a workspace

Voice

Text-to-speech and speech-to-text run on the same base URL and take the same key.

• POST /v1/tts — text to audio (audio/mpeg). Body {"text", "voice", "tenant_id"}. Voices: zh_male_m191_uranus_bigtts (classic male), zh_female_xiaohe_uranus_bigtts (classic female), ICL_uranus_zh_female_yuanqitianmei_tob (bright female). Maximum 2000 characters.
• POST /v1/stt — multipart file to {"text": "..."} (Doubao flash ASR).

Related

• Overview — the three layers and the four credentials
• Advanced — run and supervise the API process from the terminal
• Model gateway — the managed LLM endpoint, which is a different service
• Quickstart — install and connect a window