Skip to content

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.

POST
/auth/login

Authenticate a user account

GET
/auth/me

Resolve the current user

POST
/api-tokens

Create a personal access token

GET
/notifications

List account notifications

Org & workspace

The operating hierarchy is organization -> workspace -> project.

GET
/organizations

List organizations available to the caller

POST
/orgs/:orgSlug/workspaces

Create a workspace in an organization

GET
/orgs/:orgSlug/workspaces/:wsSlug

Read workspace details and caller role

POST
/invitations/:token/accept

Accept a workspace invitation

Delivery

Projects, scopes, views, columns, cards, comments, attachments, labels, and fields.

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

Create a project

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

Read project roadmap

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

Create a scope

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

Create a card

Context

Workspace documents plus card-to-document linking endpoints.

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

Create a document

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

Read the full workspace document tree

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

List card-linked documents

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

Link a document to a card

AI runtime

Workspace agents, mission execution, approvals, and project drafts.

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

Create an agent

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

Run an agent objective directly

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

Launch a card mission

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

Create an AI project draft

Platform

Plugins, skills, pipelines, and project automations.

GET
/plugins

Read the global plugin catalog

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

Create a pipeline

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

Create a project automation

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

Assign a skill to an agent

Pilotage & billing

Cockpit state, decisions, actions, portfolio, and billing flows.

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

Read cockpit dashboard state

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

Create a proposed action

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

Read portfolio-level pilotage summary

POST
/organizations/:orgSlug/billing/checkout

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

POST
/auth/login

Authenticate a user. When 2FA is required, the response returns a temporary two-factor token instead of a completed session.

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

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

GET
/auth/me

Resolve 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 https://api.stellary.co/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200
{
  "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
POST
/api-tokens

Create a new personal access token for REST or MCP usage.

Body parameters
namestringrequiredHuman-readable token name
scopesarrayOptional subset of allowed scopes
Complex type — edit in code
expiresAtstringOptional ISO timestamp
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"
}'

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

List existing tokens for the current user. The plaintext secret is never returned again.

curl https://api.stellary.co/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.

GET
/organizations

List organizations available to the current user.

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

POST
/orgs/:orgSlug/workspaces

Create a new workspace inside an organization.

Path parameters
orgSlugstringrequired
Body parameters
namestringrequiredWorkspace display name
slugstringrequiredLowercase URL slug
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

Accept a workspace invitation. This endpoint is authenticated but not org-scoped.

Path parameters
tokenstringrequired
curl -X POST https://api.stellary.co/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.

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

Create a project in a workspace.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
namestringrequiredProject name
descriptionstringOptional long description
deadlinestringOptional ISO deadline
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

Create a scope inside a project. Scope and view endpoints are split into their own controllers.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
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

Create a card directly at project level.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
Body parameters
titlestringrequiredCard title
descriptionstringOptional card body
prioritystringlow | medium | high
dueDatestringOptional ISO due date
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

Post a comment on a card.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
cardIdstringrequired
Body parameters
contentstringrequiredComment text
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 an attachment to a card.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
cardIdstringrequired
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

Document routes are workspace-scoped. They cover creation, listing, count and tree views, summaries, reviews, bulk actions, and card-level document linking.

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

Create a document inside a workspace, project, or scope context.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
titlestringrequiredDocument title
contentstringOptional source content
contentFormatstringmarkdown or tiptap_json
docTypestringdocument | spec | brief | adr | note | reference | template | spreadsheet
contextTypestringrequiredorganization | workspace | project | scope
contextIdstringrequiredID of the owning context
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

List documents linked to a card.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
cardIdstringrequired
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

Attach an existing document to a card.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
cardIdstringrequired
documentIdstringrequired
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 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.

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

Create a workspace agent.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
namestringrequiredAgent display name
slugstringrequiredLowercase unique slug
descriptionstringOptional agent description
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

Run an agent against an explicit objective.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
agentUserIdstringrequiredAgent user ID
objectivestringrequiredRun objective
projectIdstringOptional project scope
maxStepsnumberOptional runtime cap
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

Launch a mission from a card. MCP-only agents are queued and return JSON; non-MCP agents start with an SSE stream.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
cardIdstringrequiredTarget card ID
projectIdstringrequiredOwning project ID
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

List pending runtime proposals awaiting approval or rejection.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
curl https://api.stellary.co/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.

GET
/plugins

Read the global plugin catalog.

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

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

Create a pipeline definition at workspace level.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
namestringrequiredPipeline name
descriptionstringOptional pipeline description
stepsarrayrequiredPipeline graph payload
Complex type — edit in code
enabledbooleanOptional enabled flag
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

Create a project automation rule.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
projectIdstringrequired
Body parameters
namestringrequiredAutomation name
triggerstringrequiredSupported trigger identifier
actionobjectrequiredSupported action: move_card, set_status, set_priority, assign_user, or archive_card
Complex type — edit in code
enabledbooleanOptional enabled flag
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

Create an AI-assisted project draft.

Path parameters
orgSlugstringrequired
wsSlugstringrequired
Body parameters
namestringrequiredDraft name
descriptionstringOptional project brief
contextDocumentsarrayOptional context payloads
Complex type — edit in 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

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.

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

Read the consolidated cockpit dashboard state for a workspace.

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

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

Create a proposed action in pilotage.

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

POST
/organizations/:orgSlug/billing/checkout

Create a billing checkout session for the organization.

Path parameters
orgSlugstringrequired
curl -X POST https://api.stellary.co/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  /mcp
POST /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.