Skip to Content
Guide développeurRéférence de l'API REST du démon

Référence de l’API REST du démon

C’est l’interface REST/SSE publique pour les intégrations qui exécutent qwen serve --no-web et fournissent leur propre interface utilisateur. Commencez par le guide d’intégration, puis utilisez cette page pour la découverte des endpoints et la référence du protocole HTTP pour la sémantique détaillée du cycle de vie.

OpenAPI

Le contrat de 25 opérations est disponible au format OpenAPI 3.1 JSON . Importez cette URL dans un moteur de rendu, un générateur de client ou un outil de validation compatible OpenAPI. Le JSON versionné est le contrat d’interface portable pour les opérations indexées ci-dessous et est validé par rapport au guide, aux en-têtes du protocole et aux routes enregistrées dans le CI.

Cet index couvre un sous-ensemble principal de la surface REST du démon, pas la totalité. En dehors se trouvent les routes Web Shell officielles, les surfaces internes conditionnelles et d’autres routes publiques mais non essentielles : mutation de fichiers, enregistrement de workspace, organisation et génération de sessions, ainsi que les MCP, skills et providers de workspace entre autres. Ces surfaces sont annoncées par leurs propres tags de capacité ; la référence du protocole HTTP documente les surfaces de session, de statut de workspace et de fichiers, et la gestion des serveurs MCP, des providers d’authentification et de la connexion par device-flow est couverte par les notes d’authentification et de sécurité du démon. Elles sont en dehors de ce contrat, pas dépréciées.

Lecture de l’index

  • Capability est le tag de fonctionnalité à vérifier dans GET /capabilities. Un tiret cadratin signifie que l’opération n’a pas de tag de fonctionnalité dédié ; les clients qui doivent prendre en charge d’anciennes versions du démon doivent gérer 404.
  • Scope indique quel runtime possède l’opération. process-global lit l’état global du démon, selected-runtime utilise la sélection de workspace de la requête, persisted-workspace résout le stockage de session persisté, live-session-owner route par la session live, et legacy-primary cible toujours le workspace principal du démon. GET /session/:id/export est épinglé au primaire : il résout uniquement les runtimes internes gérés avant de basculer sur le workspace principal.
  • Toutes les opérations de cet index sont stables dans le contrat REST v1. Le nom de capacité déprécié unstable_session_resume est uniquement un alias ; utilisez session_resume pour la route de reprise stable.

Découverte

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

Cycle de vie de la session

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 et événements

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 retourne 202 lorsque le prompt entre dans la file d’attente, pas lorsque l’Agent termine. Abonnez-vous d’abord, puis corréléz turn_complete ou turn_error par promptId.

Permissions

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

Les nouvelles intégrations multi-workspace doivent toujours utiliser la route à portée de session. La route héritée peut retourner le même 404 pour une requête appartenant à un autre runtime que pour un vote déjà résolu.

Contexte de workspace en lecture seule

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

Ces routes singulières ciblent le workspace principal. Les intégrations qui exposent plusieurs workspaces enregistrés doivent utiliser les équivalents qualifiés par workspace documentés dans le protocole complet et le preflight workspace_qualified_rest_core.

Règles de protocole communes

  • Authentifiez les routes normales avec Authorization: Bearer <token>. Une sonde loopback /health par défaut peut être exemptée ; les liaisons non-loopback ne le sont pas.
  • Envoyez X-Qwen-Client-Id lorsqu’une réponse de création/chargement en a fourni un. C’est un identifiant de rattachement et d’attribution, pas un principal de sécurité utilisateur.
  • Considérez les corps d’erreur comme additifs. Branchez principalement sur le statut HTTP et le code stable ou errorKind lorsqu’ils sont présents.
  • Préservez les en-têtes de réponse SSE et désactivez le buffering du proxy. Reprenez avec Last-Event-ID et X-Qwen-Event-Epoch lorsque le démon a fourni un epoch.
  • Une limite de confiance de workspace n’est pas une isolation de tenant. Exécutez des démons séparés lorsque les principaux de sécurité ou les limites de défaillance au niveau processus doivent être indépendants.
Last updated on
Guide d'intégration de l'API RESTProtocole HTTP qwen serve