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.

POST

/auth/login

Authentifier un compte utilisateur

GET

/auth/me

Résoudre l'utilisateur courant

POST

/api-tokens

Créer un jeton d'accès personnel

GET

/notifications

Lister les notifications du compte

Organisation & workspace

La hiérarchie de travail est organisation -> workspace -> projet.

GET

/organizations

Lister les organisations visibles par le caller

POST

/orgs/:orgSlug/workspaces

Créer un workspace dans une organisation

GET

/orgs/:orgSlug/workspaces/:wsSlug

Lire le détail du workspace et le rôle appelant

POST

/invitations/:token/accept

Accepter une invitation de workspace

Delivery

Projets, scopes, vues, colonnes, cartes, commentaires, pièces jointes, labels et champs.

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects

Créer un projet

GET

/orgs/:orgSlug/workspaces/:wsSlug/projects/:id/roadmap

Lire la roadmap du projet

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopes

Créer un scope

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards

Créer une carte

Contexte

Documents du workspace et endpoints de liaison entre cartes et documents.

POST

/orgs/:orgSlug/workspaces/:wsSlug/documents

Créer un document

GET

/orgs/:orgSlug/workspaces/:wsSlug/documents/all

Lire tout l’arbre documentaire du workspace

GET

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents

Lister les documents liés à une carte

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents/:documentId/link

Lier un document à une carte

Runtime IA

Agents du workspace, exécution de missions, validations et project drafts.

POST

/orgs/:orgSlug/workspaces/:wsSlug/agents

Créer un agent

POST

/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/run

Lancer un objectif agent direct

POST

/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/card-mission

Lancer une mission sur carte

POST

/orgs/:orgSlug/workspaces/:wsSlug/project-drafts

Créer un brouillon de projet IA

Plateforme

Plugins, skills, pipelines et automatisations de projet.

GET

/plugins

Lire le catalogue global de plugins

POST

/orgs/:orgSlug/workspaces/:wsSlug/pipelines

Créer un pipeline

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/automations

Créer une automatisation de projet

POST

/orgs/:orgSlug/workspaces/:wsSlug/agents/:agentId/skills/:skillId

Assigner une skill à un agent

Pilotage & billing

Cockpit, décisions, actions, portfolio et flux de facturation.

GET

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboard

Lire l'état du cockpit

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/propose

Créer une action proposée

GET

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/portfolio

Lire le résumé portfolio du pilotage

POST

/organizations/:orgSlug/billing/checkout

Dé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.co
Swagger UI (non-production only): /api/docs
MCP endpoint: /mcp
Content 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.

POST

/auth/login

Authentifie un utilisateur. Quand la 2FA est requise, la réponse renvoie un jeton temporaire de second facteur au lieu d’une session complète.

Paramètres du corps

emailstringrequisAdresse email du compte

passwordstringrequisMot de passe en clair

curl -X POST https://api.stellary.co/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "alex@example.com",
  "password": "correct horse battery staple"
}'

Réponse200

{
  "access_token": "<jwt>",
  "csrfToken": "<csrf-token>",
  "user": {
    "id": "usr_123",
    "email": "alex@example.com",
    "name": "Alex",
    "emailVerified": true,
    "twoFactorEnabled": false
  }
}

GET

/auth/me

Ré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"

Réponse200

{
  "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

POST

/api-tokens

Crée un nouveau jeton d’accès personnel pour REST ou MCP.

Paramètres du corps

namestringrequisNom humain du jeton

scopesarraySous-ensemble optionnel des scopes autorisés

Type complexe — à modifier dans le code

expiresAtstringTimestamp ISO optionnel

curl -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"
}'

Réponse201

{
  "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"
}

GET

/api-tokens

Liste 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.

GET

/organizations

Liste les organisations accessibles à l’utilisateur courant.

curl https://api.stellary.co/organizations \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/orgs/:orgSlug/workspaces

Crée un nouveau workspace dans une organisation.

Paramètres de chemin

orgSlugstringrequis

Paramètres du corps

namestringrequisNom visible du workspace

slugstringrequisSlug URL en minuscules

curl -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"
}'

POST

/invitations/:token/accept

Accepte une invitation de workspace. Cet endpoint est authentifié mais n’est pas scopé par organisation.

Paramètres de chemin

tokenstringrequis

curl -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.

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects

Crée un projet dans un workspace.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

namestringrequisNom du projet

descriptionstringDescription longue optionnelle

deadlinestringDeadline ISO optionnelle

curl -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"
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopes

Crée un scope dans un projet. Les endpoints de scope et de vue sont isolés dans leurs propres controllers.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

curl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/scopes \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards

Crée une carte directement au niveau projet.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

Paramètres du corps

titlestringrequisTitre de la carte

descriptionstringContenu optionnel de la carte

prioritystringlow | medium | high

dueDatestringDate d’échéance ISO optionnelle

curl -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"
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/comments

Poste un commentaire sur une carte.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

cardIdstringrequis

Paramètres du corps

contentstringrequisTexte du commentaire

curl -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."
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/attachments

Upload une pièce jointe sur une carte.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

cardIdstringrequis

curl -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.

POST

/orgs/:orgSlug/workspaces/:wsSlug/documents

Crée un document dans un contexte workspace, projet ou scope.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

titlestringrequisTitre du document

contentstringContenu source optionnel

contentFormatstringmarkdown ou tiptap_json

contextTypestringrequisorganization | workspace | project | scope

contextIdstringrequisID du contexte propriétaire

curl -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"
  ]
}'

GET

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents

Liste les documents liés à une carte.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

cardIdstringrequis

curl https://api.stellary.co/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents/:documentId/link

Attache un document existant à une carte.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

cardIdstringrequis

documentIdstringrequis

curl -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.

POST

/orgs/:orgSlug/workspaces/:wsSlug/agents

Crée un agent de workspace.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

namestringrequisNom visible de l’agent

slugstringrequisSlug unique en minuscules

descriptionstringDescription optionnelle de l’agent

autonomyModestringautonomous | supervised | approval

curl -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
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/run

Lance un agent sur un objectif explicite.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

agentUserIdstringrequisID utilisateur agent

objectivestringrequisObjectif du run

projectIdstringScope projet optionnel

maxStepsnumberCap runtime optionnel

curl -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
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/card-mission

Lance 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.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

cardIdstringrequisID de la carte cible

projectIdstringrequisID du projet propriétaire

curl -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"
}'

GET

/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/proposals

Liste les propositions runtime en attente d’approbation ou de rejet.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

curl 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.

GET

/plugins

Lit le catalogue global de plugins.

curl https://api.stellary.co/plugins

POST

/orgs/:orgSlug/workspaces/:wsSlug/pipelines

Crée une définition de pipeline au niveau workspace.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

namestringrequisNom du pipeline

descriptionstringDescription optionnelle du pipeline

stepsarrayrequisPayload du graphe pipeline

Type complexe — à modifier dans le code

enabledbooleanFlag enabled optionnel

curl -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
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/automations

Crée une règle d’automatisation de projet.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

projectIdstringrequis

Paramètres du corps

namestringrequisNom de l’automatisation

triggerstringrequisIdentifiant du déclencheur supporté

actionobjectrequisAction supportée : move_card, set_status, set_priority, assign_user ou archive_card

Type complexe — à modifier dans le code

enabledbooleanFlag enabled optionnel

curl -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
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/project-drafts

Crée un brouillon de projet assisté par IA.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

Paramètres du corps

namestringrequisNom du brouillon

descriptionstringBrief projet optionnel

contextDocumentsarrayPayloads de contexte optionnels

Type complexe — à modifier dans le code

curl -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.

GET

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboard

Lit l’état agrégé du cockpit pour un workspace.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

curl https://api.stellary.co/orgs/acme/workspaces/eng/pilotage/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/propose

Crée une action proposée dans le pilotage.

Paramètres de chemin

orgSlugstringrequis

wsSlugstringrequis

curl -X POST https://api.stellary.co/orgs/acme/workspaces/eng/pilotage/actions/propose \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/organizations/:orgSlug/billing/checkout

Crée une session de checkout billing pour l’organisation.

Paramètres de chemin

orgSlugstringrequis

curl -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  /mcp
POST /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.