Référence API
Cette page documente la surface REST qui existe aujourd'hui dans le backend NestJS. Elle est structurée autour des vrais domaines exposés par la codebase : auth, organisations, workspaces, delivery, documents, runtime IA, pilotage, extension de plateforme et billing.
Elle complète le guide MCP : REST correspond à l’API de ressources explicite, tandis que MCP est le point d’entrée orienté outils pour les clients IA compatibles.
Identité
Auth compte, sessions, 2FA, consentement, exports et jetons API personnels.
/auth/loginAuthentifier un compte utilisateur
/auth/meRésoudre l'utilisateur courant
/api-tokensCréer un jeton d'accès personnel
/notificationsLister les notifications du compte
Organisation & workspace
La hiérarchie de travail est organisation -> workspace -> projet.
/organizationsLister les organisations visibles par le caller
/orgs/:orgSlug/workspacesCréer un workspace dans une organisation
/orgs/:orgSlug/workspaces/:wsSlugLire le détail du workspace et le rôle appelant
/invitations/:token/acceptAccepter une invitation de workspace
Delivery
Projets, scopes, vues, colonnes, cartes, commentaires, pièces jointes, labels et champs.
/orgs/:orgSlug/workspaces/:wsSlug/projectsCréer un projet
/orgs/:orgSlug/workspaces/:wsSlug/projects/:id/roadmapLire la roadmap du projet
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopesCréer un scope
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cardsCréer une carte
Contexte
Documents du workspace et endpoints de liaison entre cartes et documents.
/orgs/:orgSlug/workspaces/:wsSlug/documentsCréer un document
/orgs/:orgSlug/workspaces/:wsSlug/documents/allLire tout l’arbre documentaire du workspace
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documentsLister les documents liés à une carte
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents/:documentId/linkLier un document à une carte
Runtime IA
Agents du workspace, exécution de missions, validations et project drafts.
/orgs/:orgSlug/workspaces/:wsSlug/agentsCréer un agent
/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/runLancer un objectif agent direct
/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/card-missionLancer une mission sur carte
/orgs/:orgSlug/workspaces/:wsSlug/project-draftsCréer un brouillon de projet IA
Plateforme
Plugins, skills, pipelines et automatisations de projet.
/pluginsLire le catalogue global de plugins
/orgs/:orgSlug/workspaces/:wsSlug/pipelinesCréer un pipeline
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/automationsCréer une automatisation de projet
/orgs/:orgSlug/workspaces/:wsSlug/agents/:agentId/skills/:skillIdAssigner une skill à un agent
Pilotage & billing
Cockpit, décisions, actions, portfolio et flux de facturation.
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboardLire l'état du cockpit
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/proposeCréer une action proposée
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/portfolioLire le résumé portfolio du pilotage
/organizations/:orgSlug/billing/checkoutDémarrer un checkout billing
Vue d'ensemble
Stellary ne monte pas actuellement ses routes de ressources derrière un préfixe global /api. Les endpoints REST vivent à la racine de l’application, tandis que l’interface Swagger est exposée séparément en environnement non-production.
REST base URL: https://api.stellary.coSwagger UI (non-production only): /api/docsMCP endpoint: /mcpContent type: application/json
Attachment uploads use multipart/form-data.Modèle des routes
L’API reflète la hiérarchie produit. Les routes scopées par workspace dominent la surface, et les ressources de delivery vivent en dessous.
/organizations/:orgSlug/orgs/:orgSlug/workspaces/:wsSlug/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopes/:scopeId/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId ...Authentification
Les endpoints protégés utilisent la même résolution d’auth que le produit lui-même. Le guard essaie d’abord un jeton Bearer, puis retombe sur la session cookie authentifiée utilisée par la web app.
Authorization: Bearer <jwt-or-personal-access-token>Les JWT proviennent des flux sous /auth. Les jetons d’accès personnels sont créés sous /api-tokens et sont aussi valides pour /mcp.
/auth/loginAuthentifie un utilisateur. Quand la 2FA est requise, la réponse renvoie un jeton temporaire de second facteur au lieu d’une session complète.
emailstringrequiredAdresse email du comptepasswordstringrequiredMot de passe en claircurl -X POST https://api.stellary.co/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "alex@example.com", "password": "correct horse battery staple"}'{ "access_token": "<jwt>", "csrfToken": "<csrf-token>", "user": { "id": "usr_123", "email": "alex@example.com", "name": "Alex", "emailVerified": true, "twoFactorEnabled": false }}/auth/meRésout l’utilisateur courant depuis un Bearer token ou le cookie de session. Le backend peut aussi renvoyer le CSRF token pour permettre au frontend de restaurer son état local.
curl https://api.stellary.co/auth/me \ -H "Authorization: Bearer YOUR_TOKEN"{ "user": { "id": "usr_123", "email": "alex@example.com", "name": "Alex", "jobTitle": "CTO", "emailVerified": true, "twoFactorEnabled": true }, "csrfToken": "<csrf-token>"}Jetons API
Les jetons d'accès personnels se gèrent via des endpoints protégés par JWT. Le secret du jeton n'est renvoyé qu'une seule fois à la création ; ensuite seule sa métadonnée reste visible.
Scopes disponibles:- projects:read- projects:write- pilotage:read- pilotage:write- notifications:read- account:read- account:write/api-tokensCrée un nouveau jeton d’accès personnel pour REST ou MCP.
namestringrequiredNom humain du jetonscopesarraySous-ensemble optionnel des scopes autorisésexpiresAtstringTimestamp ISO optionnelcurl -X POST https://api.stellary.co/api-tokens \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "CI pipeline", "scopes": [ "projects:read", "projects:write" ], "expiresAt": "2027-01-01T00:00:00.000Z"}'{ "id": "tok_123", "name": "CI pipeline", "tokenPrefix": "sl_abcd12", "scopes": ["projects:read", "projects:write"], "expiresAt": "2027-01-01T00:00:00.000Z", "secret": "sl_very_secret_value", "createdAt": "2026-04-10T10:00:00.000Z"}/api-tokensListe les jetons existants de l’utilisateur courant. Le secret en clair n’est jamais renvoyé à nouveau.
curl https://api.stellary.co/api-tokens \ -H "Authorization: Bearer YOUR_TOKEN"Erreurs
Le filtre global d'exceptions HTTP normalise les erreurs framework et validation dans une structure JSON prévisible. Les détails de validation peuvent ajouter des champs, mais la forme top-level reste stable.
{ "statusCode": 400, "message": "Project name is required", "error": "Bad Request"}Organisations & workspaces
Les routes organisation gèrent la tenancy et la gouvernance transversale. Les routes workspace ajoutent la gestion des membres, les invitations, les lectures role-aware et les réglages du workspace. La plupart des endpoints de workspace combinent auth, accès org, accès workspace et permission guards.
/organizationsListe les organisations accessibles à l’utilisateur courant.
curl https://api.stellary.co/organizations \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspacesCrée un nouveau workspace dans une organisation.
orgSlugstringrequirednamestringrequiredNom visible du workspaceslugstringrequiredSlug URL en minusculescurl -X POST https://api.stellary.co/orgs/acme/workspaces \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Core delivery", "slug": "core-delivery"}'/invitations/:token/acceptAccepte une invitation de workspace. Cet endpoint est authentifié mais n’est pas scopé par organisation.
tokenstringrequiredcurl -X POST https://api.stellary.co/invitations/INVITE_TOKEN/accept \ -H "Authorization: Bearer YOUR_TOKEN"Projets & delivery
Les routes de delivery vivent sous le workspace et couvrent projets, scopes, vues, colonnes, cartes, sous-tâches, commentaires et pièces jointes. Les routes projet exposent aussi la roadmap et les endpoints de knowledge du projet.
/orgs/:orgSlug/workspaces/:wsSlug/projectsCrée un projet dans un workspace.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredNom du projetdescriptionstringDescription longue optionnelledeadlinestringDeadline ISO optionnellecurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Checkout refactor", "description": "Stabilize the payment flow", "deadline": "2026-06-01T00:00:00.000Z"}'/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopesCrée un scope dans un projet. Les endpoints de scope et de vue sont isolés dans leurs propres controllers.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/scopes \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cardsCrée une carte directement au niveau projet.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredtitlestringrequiredTitre de la cartedescriptionstringContenu optionnel de la carteprioritystringlow | medium | highdueDatestringDate d’échéance ISO optionnellecurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Ship rollback-safe payment webhook", "description": "Add retries and observability", "priority": "high", "dueDate": "2026-04-20T12:00:00.000Z"}'/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/commentsPoste un commentaire sur une carte.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcontentstringrequiredTexte du commentairecurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/comments \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content": "Release candidate is ready for review."}'/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/attachmentsUpload une pièce jointe sur une carte.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/attachments \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@./document.pdf"Documents
Les routes documents sont scopées par workspace. Elles couvrent création, listing, vues count et tree, summaries, reviews, bulk actions et liaison document-carte.
/orgs/:orgSlug/workspaces/:wsSlug/documentsCrée un document dans un contexte workspace, projet ou scope.
orgSlugstringrequiredwsSlugstringrequiredtitlestringrequiredTitre du documentcontentstringContenu source optionnelcontentFormatstringmarkdown ou tiptap_jsondocTypestringdocument | spec | brief | adr | note | reference | template | spreadsheetcontextTypestringrequiredorganization | workspace | project | scopecontextIdstringrequiredID du contexte propriétairecurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/documents \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Payment retry policy", "content": "# Payment retry policy", "contentFormat": "markdown", "docType": "spec", "contextType": "project", "contextId": "prj_123", "tags": [ "payments", "resilience" ]}'/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documentsListe les documents liés à une carte.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcurl https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/documents \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents/:documentId/linkAttache un document existant à une carte.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequireddocumentIdstringrequiredcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/documents/DOCUMENTID/link \ -H "Authorization: Bearer YOUR_TOKEN"Agents & runtime
Stellary distingue les endpoints de configuration des agents et les endpoints d’exécution runtime. Les agents sont des service users scopés par workspace ; le runtime lance des runs directs, des missions sur cartes, des validations de propositions et des flux de progression.
/orgs/:orgSlug/workspaces/:wsSlug/agentsCrée un agent de workspace.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredNom visible de l’agentslugstringrequiredSlug unique en minusculesdescriptionstringDescription optionnelle de l’agentautonomyModestringautonomous | supervised | approvalcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/agents \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Delivery reviewer", "slug": "delivery-reviewer", "description": "Reviews risky work before apply", "autonomyMode": "approval", "tools": [ "read_board", "write_comments" ], "mcpOnly": false}'/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/runLance un agent sur un objectif explicite.
orgSlugstringrequiredwsSlugstringrequiredagentUserIdstringrequiredID utilisateur agentobjectivestringrequiredObjectif du runprojectIdstringScope projet optionnelmaxStepsnumberCap runtime optionnelcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/agent-runtime/run \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentUserId": "usr_agent_123", "objective": "Summarize blockers on the checkout project", "projectId": "prj_123", "maxSteps": 8}'/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/card-missionLance une mission depuis une carte. Les agents MCP-only sont queues et renvoient du JSON ; les agents non-MCP démarrent avec un flux SSE.
orgSlugstringrequiredwsSlugstringrequiredcardIdstringrequiredID de la carte cibleprojectIdstringrequiredID du projet propriétairecurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/agent-runtime/card-mission \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cardId": "card_123", "projectId": "prj_123"}'/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/proposalsListe les propositions runtime en attente d’approbation ou de rejet.
orgSlugstringrequiredwsSlugstringrequiredcurl https://api.stellary.co/orgs/acme/workspaces/eng/agent-runtime/proposals \ -H "Authorization: Bearer YOUR_TOKEN"Plateforme & orchestration
La couche plateforme expose le catalogue de plugins, l’installation de plugins de workspace, les skills du workspace, l’assignation de skills aux agents, l’authoring de pipelines et les règles d’automatisation de projet.
/pluginsLit le catalogue global de plugins.
curl https://api.stellary.co/plugins/orgs/:orgSlug/workspaces/:wsSlug/pipelinesCrée une définition de pipeline au niveau workspace.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredNom du pipelinedescriptionstringDescription optionnelle du pipelinestepsarrayrequiredPayload du graphe pipelineenabledbooleanFlag enabled optionnelcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/pipelines \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Review before merge", "description": "Run agent review before human approval", "steps": [], "enabled": true}'/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/automationsCrée une règle d’automatisation de projet.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequirednamestringrequiredNom de l’automatisationtriggerstringrequiredIdentifiant du déclencheur supportéactionobjectrequiredAction supportée : move_card, set_status, set_priority, assign_user ou archive_cardenabledbooleanFlag enabled optionnelcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/automations \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Escalate overdue card", "trigger": "due_date_reached", "action": { "type": "set_priority", "priority": "high" }, "enabled": true}'/orgs/:orgSlug/workspaces/:wsSlug/project-draftsCrée un brouillon de projet assisté par IA.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredNom du brouillondescriptionstringBrief projet optionnelcontextDocumentsarrayPayloads de contexte optionnelscurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/project-drafts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Checkout stabilization", "description": "Reduce payment failure rate", "contextDocuments": [ "Base64-or-text-doc" ], "teamMembers": [ { "name": "Alex", "role": "Engineering lead" } ]}'Pilotage & billing
Les routes pilotage alimentent le cockpit. Elles couvrent dashboard, events, missions, priorities, todos, decisions, standing orders, génération de briefing, actions proposées, vues portfolio et préférences utilisateur. Les endpoints billing sont scopés par organisation et séparés du control surface workspace.
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboardLit l’état agrégé du cockpit pour un workspace.
orgSlugstringrequiredwsSlugstringrequiredcurl https://api.stellary.co/orgs/acme/workspaces/eng/pilotage/dashboard \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/proposeCrée une action proposée dans le pilotage.
orgSlugstringrequiredwsSlugstringrequiredcurl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/pilotage/actions/propose \ -H "Authorization: Bearer YOUR_TOKEN"/organizations/:orgSlug/billing/checkoutCrée une session de checkout billing pour l’organisation.
orgSlugstringrequiredcurl -X POST https://api.stellary.co/organizations/acme/billing/checkout \ -H "Authorization: Bearer YOUR_TOKEN"MCP
MCP est exposé comme endpoint protocolaire, pas comme collection de ressources REST. Le backend accepte GET /mcp et POST /mcp, avec la même résolution Bearer auth que l’API REST.
GET /mcpPOST /mcp
Authorization: Bearer <jwt-or-sl_token-or-MCP_TOKEN>Utilise le guide MCP pour le setup client et le comportement runtime. Utilise cette référence API quand tu as besoin du modèle de routes REST explicite.
Pour la mise en route produit, continue avec Démarrage rapide. Pour l’outillage agent et les clients IA externes, continue avec Intégration MCP.
Pour une lecture plus large du marché, voir Gestion de projet avec des agents IA et Logiciels de gestion de projet IA en 2026.