Daemon-REST-API-Referenz

Dies ist die öffentliche REST/SSE-Schnittstelle für Integrationen, die qwen serve --no-web ausführen und eine eigene UI bereitstellen. Beginnen Sie mit dem Integrationsleitfaden, verwenden Sie dann diese Seite für die Endpunkt- Erkundung und die HTTP-Protokollreferenz für detaillierte Lebenszyklus-Semantik.

OpenAPI

Der kuratierte 25-Operation-Vertrag ist als OpenAPI 3.1 JSON verfügbar. Importieren Sie diese URL in einen OpenAPI-kompatiblen Renderer, Client-Generator oder Validierungstool. Das eingecheckte JSON ist der portable Schnittstellenvertrag für die unten indizierten Operationen und wird im CI gegen den Leitfaden, die Protokoll-Überschriften und die registrierten Routen validiert.

Dieser Index deckt eine kuratierte Kern-Teilmenge der REST-Oberfläche des Daemons ab, nicht alles. Außerhalb befinden sich die erstklassigen WebShell-Routen, bedingte interne Oberflächen und andere öffentliche, aber nicht zum Kern gehörende Routen: Datei-Mutation, Workspace-Registrierung, Session-Organisation und -Generierung sowie Workspace-MCP, Skills und Provider unter anderem. Diese Oberflächen werden durch ihre eigenen Capability-Tags gekennzeichnet; die HTTP-Protokollreferenz dokumentiert die Session-, Workspace-Status- und Datei-Oberflächen, und MCP-Server-Verwaltung, Auth-Provider und Device-Flow-Anmeldung werden in den Daemon-Auth- und Sicherheitshinweisen behandelt. Sie sind außerhalb dieses Vertrags, nicht deprecated.

Den Index lesen

Capability ist das Feature-Tag, das in GET /capabilities geprüft werden soll. Ein Gedankenstrich bedeutet, dass die Operation kein eigenes Feature-Tag hat; Clients, die ältere Daemon-Builds unterstützen müssen, sollten 404 behandeln.
Scope gibt an, welche Runtime die Operation besitzt. process-global liest Daemon-weiten Zustand, selected-runtime verwendet die Workspace-Auswahl der Anfrage, persisted-workspace löst persistierte Session-Speicher auf, live-session-owner routet über die Live-Session, und legacy-primary zielt immer auf den primären Workspace des Daemons. GET /session/:id/export ist primär-angeheftet: es löst nur verwaltete interne Runtimes auf, bevor es auf den primären Workspace zurückfällt.
Alle Operationen in diesem Index sind im v1-REST-Vertrag stabil. Der deprecated Capability-Name unstable_session_resume ist nur ein Alias; verwenden Sie session_resume für die stabile Resume-Route.

Discovery

Operation	Capability	Scope	TypeScript SDK
`GET /health`	`health`	`process-global`	`DaemonClient.health`
`GET /capabilities`	`capabilities`	`process-global`	`DaemonClient.capabilities`

Session-Lebenszyklus

Operation	Capability	Scope	TypeScript SDK
`POST /session`	`session_create`	`selected-runtime`	`DaemonClient.createOrAttachSession`
`POST /session/:id/load`	`session_load`	`selected-runtime`	`DaemonClient.loadSession`
`POST /session/:id/resume`	`session_resume`	`selected-runtime`	`DaemonClient.resumeSession`
`POST /session/:id/heartbeat`	`client_heartbeat`	`live-session-owner`	`DaemonClient.heartbeat`
`PATCH /session/:id/metadata`	`session_metadata`	`live-session-owner`	`DaemonClient.updateSessionMetadata`
`POST /session/:id/model`	`session_set_model`	`live-session-owner`	`DaemonClient.setSessionModel`
`DELETE /session/:id`	`session_close`	`live-session-owner`	`DaemonClient.closeSession`

Prompts und Events

Operation	Capability	Scope	TypeScript SDK
`GET /session/:id/status`	`session_status`	`live-session-owner`	`DaemonClient.sessionStatus`
`POST /session/:id/prompt`	`session_prompt`	`live-session-owner`	`DaemonClient.promptNonBlocking`
`POST /session/:id/cancel`	`session_cancel`	`live-session-owner`	`DaemonClient.cancel`
`GET /session/:id/events`	`session_events`	`live-session-owner`	`DaemonClient.subscribeEvents`
`GET /session/:id/transcript`	`session_transcript`	`persisted-workspace`	`DaemonClient.getSessionTranscriptPage`
`GET /session/:id/context`	`session_context`	`live-session-owner`	`DaemonClient.sessionContext`
`GET /session/:id/export`	`session_export`	`legacy-primary`	`DaemonClient.exportSession`
`GET /session/:id/pending-prompts`	—	`live-session-owner`	`DaemonClient.getPendingPrompts`

POST /session/:id/prompt gibt 202 zurück, wenn der Prompt die Warteschlange betritt, nicht wenn der Agent fertig ist. Abonnieren Sie zuerst, dann korrelieren Sie turn_complete oder turn_error über promptId.

Berechtigungen

Operation	Capability	Scope	TypeScript SDK
`POST /session/:id/permission/:requestId`	`session_permission_vote`	`live-session-owner`	`DaemonClient.respondToSessionPermission`
`POST /permission/:requestId`	`permission_vote`	`legacy-primary`	`DaemonClient.respondToPermission`

Neue Multi-Workspace-Integrationen sollten immer die Session-scoped Route verwenden. Die Legacy-Route kann für eine Anfrage, die einer anderen Runtime gehört, denselben 404 zurückgeben wie für eine bereits aufgelöste Abstimmung.

Schreibgeschützter Workspace-Kontext

Operation	Capability	Scope	TypeScript SDK
`GET /workspace/tools`	—	`legacy-primary`	`DaemonClient.workspaceTools`
`GET /file`	`workspace_file_read`	`legacy-primary`	`DaemonClient.readWorkspaceFile`
`GET /file/bytes`	`workspace_file_bytes`	`legacy-primary`	`DaemonClient.readWorkspaceFileBytes`
`GET /stat`	`workspace_file_read`	`legacy-primary`	`DaemonClient.fileStat`
`GET /list`	`workspace_file_read`	`legacy-primary`	`DaemonClient.dirList`
`GET /glob`	`workspace_file_read`	`legacy-primary`	`DaemonClient.glob`

Diese singulären Routen zielen auf den primären Workspace. Integrationen, die mehrere registrierte Workspaces bereitstellen, sollten die Workspace-qualifizierten Gegenstücke verwenden, die im vollständigen Protokoll dokumentiert sind, und workspace_qualified_rest_core vorab prüfen.

Gemeinsame Protokollregeln

Authentifizieren Sie normale Routen mit Authorization: Bearer <token>. Eine Standard- Loopback-/health-Probe kann ausgenommen sein; Non-Loopback-Binds sind es nicht.
Senden Sie X-Qwen-Client-Id, wenn eine Create/Load-Antwort eines bereitgestellt hat. Es ist ein Zuordnungs- und Attributions-Identifier, kein Endnutzer-Sicherheitsprinzipal.
Behandeln Sie Fehler-Bodys als additiv. Verzweigen Sie primär über HTTP-Status und den stabilen code oder errorKind, falls vorhanden.
Bewahren Sie SSE-Antwort-Header auf und deaktivieren Sie Proxy-Buffering. Setzen Sie mit beiden Last-Event-ID und X-Qwen-Event-Epoch fort, wenn der Daemon eine Epoch bereitgestellt hat.
Eine Workspace-Trust-Grenze ist keine Tenant-Isolation. Führen Sie separate Daemons aus, wenn Sicherheitsprinzipale oder Prozess-Level-Fehlerschranken unabhängig sein müssen.