Skip to Content
Developer GuideDaemon REST API Reference

Daemon REST API Reference

This is the public REST/SSE interface for integrations that run qwen serve --no-web and provide their own UI. Start with the integration guide, then use this page for endpoint discovery and the HTTP protocol reference for detailed lifecycle semantics.

OpenAPI

The curated 25-operation contract is available as OpenAPI 3.1 JSON . Import that URL into an OpenAPI-compatible renderer, client generator, or validation tool. The checked-in JSON is the portable interface contract for the operations indexed below and is validated against the guide, protocol headings, and registered routes in CI.

This index covers a curated core subset of the daemon’s REST surface, not all of it. Outside it are the first-party Web Shell routes, conditional internal surfaces, and other public but non-core routes: file mutation, workspace registration, session organization and generation, and workspace MCP, skills, and providers among them. Those surfaces are advertised by their own capability tags; the HTTP protocol reference documents the session, workspace-status, and file surfaces, and MCP server management, auth providers, and device-flow sign-in are covered by the daemon auth and security notes. They are outside this contract, not deprecated.

Reading the index

  • Capability is the feature tag to check in GET /capabilities. An em dash means the operation has no dedicated feature tag; clients that need to support older daemon builds should handle 404.
  • Scope says which runtime owns the operation. process-global reads daemon-wide state, selected-runtime uses the request’s workspace selection, persisted-workspace resolves persisted session storage, live-session-owner routes by the live session, and legacy-primary always targets the daemon’s primary workspace. GET /session/:id/export is primary-pinned: it resolves only managed internal runtimes before falling back to the primary workspace.
  • All operations in this index are stable in the v1 REST contract. The deprecated unstable_session_resume capability name is only an alias; use session_resume for the stable resume route.

Discovery

OperationCapabilityScopeTypeScript SDK
GET /healthhealthprocess-globalDaemonClient.health
GET /capabilitiescapabilitiesprocess-globalDaemonClient.capabilities

Session lifecycle

OperationCapabilityScopeTypeScript SDK
POST /sessionsession_createselected-runtimeDaemonClient.createOrAttachSession
POST /session/:id/loadsession_loadselected-runtimeDaemonClient.loadSession
POST /session/:id/resumesession_resumeselected-runtimeDaemonClient.resumeSession
POST /session/:id/heartbeatclient_heartbeatlive-session-ownerDaemonClient.heartbeat
PATCH /session/:id/metadatasession_metadatalive-session-ownerDaemonClient.updateSessionMetadata
POST /session/:id/modelsession_set_modellive-session-ownerDaemonClient.setSessionModel
DELETE /session/:idsession_closelive-session-ownerDaemonClient.closeSession

Prompts and events

OperationCapabilityScopeTypeScript SDK
GET /session/:id/statussession_statuslive-session-ownerDaemonClient.sessionStatus
POST /session/:id/promptsession_promptlive-session-ownerDaemonClient.promptNonBlocking
POST /session/:id/cancelsession_cancellive-session-ownerDaemonClient.cancel
GET /session/:id/eventssession_eventslive-session-ownerDaemonClient.subscribeEvents
GET /session/:id/transcriptsession_transcriptpersisted-workspaceDaemonClient.getSessionTranscriptPage
GET /session/:id/contextsession_contextlive-session-ownerDaemonClient.sessionContext
GET /session/:id/exportsession_exportlegacy-primaryDaemonClient.exportSession
GET /session/:id/pending-prompts—live-session-ownerDaemonClient.getPendingPrompts

POST /session/:id/prompt returns 202 when the prompt enters the queue, not when the Agent finishes. Subscribe first, then correlate turn_complete or turn_error by promptId.

Permissions

OperationCapabilityScopeTypeScript SDK
POST /session/:id/permission/:requestIdsession_permission_votelive-session-ownerDaemonClient.respondToSessionPermission
POST /permission/:requestIdpermission_votelegacy-primaryDaemonClient.respondToPermission

New multi-workspace integrations should always use the session-scoped route. The legacy route can return the same 404 for a request owned by another runtime as it does for an already-resolved vote.

Read-only workspace context

OperationCapabilityScopeTypeScript SDK
GET /workspace/tools—legacy-primaryDaemonClient.workspaceTools
GET /fileworkspace_file_readlegacy-primaryDaemonClient.readWorkspaceFile
GET /file/bytesworkspace_file_byteslegacy-primaryDaemonClient.readWorkspaceFileBytes
GET /statworkspace_file_readlegacy-primaryDaemonClient.fileStat
GET /listworkspace_file_readlegacy-primaryDaemonClient.dirList
GET /globworkspace_file_readlegacy-primaryDaemonClient.glob

These singular routes target the primary workspace. Integrations that expose multiple registered workspaces should use the workspace-qualified counterparts documented in the full protocol and preflight workspace_qualified_rest_core.

Common protocol rules

  • Authenticate normal routes with Authorization: Bearer <token>. A default loopback /health probe may be exempt; non-loopback binds are not.
  • Send X-Qwen-Client-Id when a create/load response supplied one. It is an attachment and attribution identifier, not an end-user security principal.
  • Treat error bodies as additive. Branch primarily on HTTP status and the stable code or errorKind when present.
  • Preserve SSE response headers and disable proxy buffering. Resume with both Last-Event-ID and X-Qwen-Event-Epoch when the daemon supplied an epoch.
  • A workspace trust boundary is not tenant isolation. Run separate daemons when security principals or process-level failure boundaries must be independent.
Last updated on
REST API integration guideqwen serve HTTP protocol