API Reference
This page documents the REST surface that exists in the NestJS backend today. It is organized around the actual product domains exposed by the codebase: auth, organizations, workspaces, delivery, documents, AI runtime, pilotage, platform extension, and billing.
It complements the MCP guide: REST is the explicit resource API, while MCP is the tool-oriented entry point used by compatible AI clients.
Identity
Account auth, sessions, 2FA, consent, exports, and personal API tokens.
/auth/loginAuthenticate a user account
/auth/meResolve the current user
/api-tokensCreate a personal access token
/notificationsList account notifications
Org & workspace
The operating hierarchy is organization -> workspace -> project.
/organizationsList organizations available to the caller
/orgs/:orgSlug/workspacesCreate a workspace in an organization
/orgs/:orgSlug/workspaces/:wsSlugRead workspace details and caller role
/invitations/:token/acceptAccept a workspace invitation
Delivery
Projects, scopes, views, columns, cards, comments, attachments, labels, and fields.
/orgs/:orgSlug/workspaces/:wsSlug/projectsCreate a project
/orgs/:orgSlug/workspaces/:wsSlug/projects/:id/roadmapRead project roadmap
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/scopesCreate a scope
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cardsCreate a card
Context
Workspace documents plus card-to-document linking endpoints.
/orgs/:orgSlug/workspaces/:wsSlug/documentsCreate a document
/orgs/:orgSlug/workspaces/:wsSlug/documents/allRead the full workspace document tree
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documentsList card-linked documents
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cards/:cardId/documents/:documentId/linkLink a document to a card
AI runtime
Workspace agents, mission execution, approvals, and project drafts.
/orgs/:orgSlug/workspaces/:wsSlug/agentsCreate an agent
/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/runRun an agent objective directly
/orgs/:orgSlug/workspaces/:wsSlug/agent-runtime/card-missionLaunch a card mission
/orgs/:orgSlug/workspaces/:wsSlug/project-draftsCreate an AI project draft
Platform
Plugins, skills, pipelines, and project automations.
/pluginsRead the global plugin catalog
/orgs/:orgSlug/workspaces/:wsSlug/pipelinesCreate a pipeline
/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/automationsCreate a project automation
/orgs/:orgSlug/workspaces/:wsSlug/agents/:agentId/skills/:skillIdAssign a skill to an agent
Pilotage & billing
Cockpit state, decisions, actions, portfolio, and billing flows.
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboardRead cockpit dashboard state
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/proposeCreate a proposed action
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/portfolioRead portfolio-level pilotage summary
/organizations/:orgSlug/billing/checkoutStart a billing checkout flow
Overview
Stellary does not currently mount its resource routes behind a global /api prefix. REST endpoints live at the application root, while the Swagger UI is exposed separately in non-production builds.
REST base URL: http://localhost:3001Swagger UI (non-production only): /api/docsMCP endpoint: /mcpContent type: application/json
Attachment uploads use multipart/form-data.Route model
The API mirrors the product hierarchy. Workspace-scoped routes dominate the surface, and project delivery resources sit below them.
/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 ...Authentication
Protected endpoints use the same backend auth resolution as the product itself. The guard first tries a Bearer token, then falls back to the authenticated session cookie used by the web app.
Authorization: Bearer <jwt-or-personal-access-token>JWTs come from the auth flows under /auth. Personal access tokens are created under /api-tokens and are also valid for /mcp.
/auth/loginAuthenticate a user. When 2FA is required, the response returns a temporary two-factor token instead of a completed session.
emailstringrequiredAccount email addresspasswordstringrequiredPlaintext passwordcurl -X POST http://localhost:3001/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/meResolve the current user from a Bearer token or the session cookie. The backend may also return the CSRF token so the frontend can restore local state.
curl http://localhost:3001/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>"}API tokens
Personal access tokens are JWT-authenticated management endpoints. The token secret is only returned once at creation and later appears as a prefix plus metadata.
Available scopes:- projects:read- projects:write- pilotage:read- pilotage:write- notifications:read- account:read- account:write/api-tokensCreate a new personal access token for REST or MCP usage.
namestringrequiredHuman-readable token namescopesarrayOptional subset of allowed scopesexpiresAtstringOptional ISO timestampcurl -X POST http://localhost:3001/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-tokensList existing tokens for the current user. The plaintext secret is never returned again.
curl http://localhost:3001/api-tokens \ -H "Authorization: Bearer YOUR_TOKEN"Errors
The global HTTP exception filter normalizes framework and validation errors into a predictable JSON shape. Validation payload details may add extra fields, but the top-level structure stays stable.
{ "statusCode": 400, "message": "Project name is required", "error": "Bad Request"}Organizations & workspaces
Organization routes handle tenancy and cross-workspace governance. Workspace routes add member management, invitations, role-aware reads, and workspace settings. Most workspace endpoints combine auth, org access, workspace access, and permission guards.
/organizationsList organizations available to the current user.
curl http://localhost:3001/organizations \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspacesCreate a new workspace inside an organization.
orgSlugstringrequirednamestringrequiredWorkspace display nameslugstringrequiredLowercase URL slugcurl -X POST http://localhost:3001/orgs/acme/workspaces \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Core delivery", "slug": "core-delivery"}'/invitations/:token/acceptAccept a workspace invitation. This endpoint is authenticated but not org-scoped.
tokenstringrequiredcurl -X POST http://localhost:3001/invitations/INVITE_TOKEN/accept \ -H "Authorization: Bearer YOUR_TOKEN"Projects & delivery
Delivery routes live below the workspace and cover projects, scopes, views, columns, cards, subtasks, comments, and attachments. Project routes also expose roadmap and project knowledge endpoints.
/orgs/:orgSlug/workspaces/:wsSlug/projectsCreate a project in a workspace.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredProject namedescriptionstringOptional long descriptiondeadlinestringOptional ISO deadlinecurl -X POST http://localhost:3001/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/scopesCreate a scope inside a project. Scope and view endpoints are split into their own controllers.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcurl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/scopes \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/cardsCreate a card directly at project level.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredtitlestringrequiredCard titledescriptionstringOptional card bodyprioritystringlow | medium | highdueDatestringOptional ISO due datecurl -X POST http://localhost:3001/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/commentsPost a comment on a card.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcontentstringrequiredComment textcurl -X POST http://localhost:3001/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 an attachment to a card.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcurl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/attachments \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@./document.pdf"Documents
Document routes are workspace-scoped. They cover creation, listing, count and tree views, summaries, reviews, bulk actions, and card-level document linking.
/orgs/:orgSlug/workspaces/:wsSlug/documentsCreate a document inside a workspace, project, or scope context.
orgSlugstringrequiredwsSlugstringrequiredtitlestringrequiredDocument titlecontentstringOptional source contentcontentFormatstringmarkdown or tiptap_jsondocTypestringdocument | spec | brief | adr | note | reference | template | spreadsheetcontextTypestringrequiredorganization | workspace | project | scopecontextIdstringrequiredID of the owning contextcurl -X POST http://localhost:3001/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/documentsList documents linked to a card.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequiredcurl http://localhost:3001/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/linkAttach an existing document to a card.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequiredcardIdstringrequireddocumentIdstringrequiredcurl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/documents/DOCUMENTID/link \ -H "Authorization: Bearer YOUR_TOKEN"Agents & runtime
Stellary distinguishes between agent configuration endpoints and runtime execution endpoints. Agents are workspace-scoped service users; the runtime launches direct runs, card missions, proposal approvals, and mission progress streams.
/orgs/:orgSlug/workspaces/:wsSlug/agentsCreate a workspace agent.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredAgent display nameslugstringrequiredLowercase unique slugdescriptionstringOptional agent descriptionautonomyModestringautonomous | supervised | approvalcurl -X POST http://localhost:3001/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/runRun an agent against an explicit objective.
orgSlugstringrequiredwsSlugstringrequiredagentUserIdstringrequiredAgent user IDobjectivestringrequiredRun objectiveprojectIdstringOptional project scopemaxStepsnumberOptional runtime capcurl -X POST http://localhost:3001/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-missionLaunch a mission from a card. MCP-only agents are queued and return JSON; non-MCP agents start with an SSE stream.
orgSlugstringrequiredwsSlugstringrequiredcardIdstringrequiredTarget card IDprojectIdstringrequiredOwning project IDcurl -X POST http://localhost:3001/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/proposalsList pending runtime proposals awaiting approval or rejection.
orgSlugstringrequiredwsSlugstringrequiredcurl http://localhost:3001/orgs/acme/workspaces/eng/agent-runtime/proposals \ -H "Authorization: Bearer YOUR_TOKEN"Platform & orchestration
The platform layer exposes plugin catalog routes, workspace plugin installation, workspace skills, agent skill assignment, pipeline authoring and runs, and project automation rules.
/pluginsRead the global plugin catalog.
curl http://localhost:3001/plugins/orgs/:orgSlug/workspaces/:wsSlug/pipelinesCreate a pipeline definition at workspace level.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredPipeline namedescriptionstringOptional pipeline descriptionstepsarrayrequiredPipeline graph payloadenabledbooleanOptional enabled flagcurl -X POST http://localhost:3001/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/automationsCreate a project automation rule.
orgSlugstringrequiredwsSlugstringrequiredprojectIdstringrequirednamestringrequiredAutomation nametriggerstringrequiredSupported trigger identifieractionobjectrequiredAction payloadenabledbooleanOptional enabled flagcurl -X POST http://localhost:3001/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": "notify" }, "enabled": true}'/orgs/:orgSlug/workspaces/:wsSlug/project-draftsCreate an AI-assisted project draft.
orgSlugstringrequiredwsSlugstringrequirednamestringrequiredDraft namedescriptionstringOptional project briefcontextDocumentsarrayOptional context payloadscurl -X POST http://localhost:3001/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
Pilotage routes power the cockpit. They cover dashboard state, events, missions, priorities, todos, decisions, standing orders, briefing generation, proposed actions, portfolio views, and user preferences. Billing endpoints are organization-scoped and separate from the workspace control surface.
/orgs/:orgSlug/workspaces/:wsSlug/pilotage/dashboardRead the consolidated cockpit dashboard state for a workspace.
orgSlugstringrequiredwsSlugstringrequiredcurl http://localhost:3001/orgs/acme/workspaces/eng/pilotage/dashboard \ -H "Authorization: Bearer YOUR_TOKEN"/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/proposeCreate a proposed action in pilotage.
orgSlugstringrequiredwsSlugstringrequiredcurl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/actions/propose \ -H "Authorization: Bearer YOUR_TOKEN"/organizations/:orgSlug/billing/checkoutCreate a billing checkout session for the organization.
orgSlugstringrequiredcurl -X POST http://localhost:3001/organizations/acme/billing/checkout \ -H "Authorization: Bearer YOUR_TOKEN"MCP
MCP is exposed as a protocol endpoint, not as a REST resource collection. The backend accepts both GET /mcp and POST /mcp, using the same Bearer auth resolution as the REST API.
GET /mcpPOST /mcp
Authorization: Bearer <jwt-or-sl_token-or-MCP_TOKEN>Use the dedicated MCP guide for client setup and runtime behavior. Use this API reference when you need the explicit REST route model.
For user-facing setup, continue with Getting Started. For agent tooling and external AI clients, continue with MCP Integration.
For a broader market view, read Project management with AI agents and AI project management software in 2026.