API Reference

The Stellary REST API lets you programmatically manage organizations, workspaces, projects, boards, cards, and strategic pilotage. All endpoints return JSON.

Base URL: http://localhost:3001 (self-hosted) or your deployment URL.

Authentication

Stellary supports two authentication methods. Both use the Authorization header with a Bearer token:

Authorization: Bearer <token>

JWT Tokens

Obtained by calling POST /auth/login or POST /auth/register. JWTs expire after 7 days by default (configurable via JWT_EXPIRES_IN).

Personal Access Tokens (PAT)

Created via POST /api-tokens. PATs support scoped permissions and optional expiration. The full token is only returned at creation — store it securely.

Both token types work with all endpoints. The backend tries JWT validation first, then PAT lookup.

Authorization Hierarchy

Bearer Token validated (JWT or PAT)
  ↓
OrgAccessGuard → checks user is a member of :orgSlug
  ↓
WorkspaceAccessGuard → checks user is a member of :wsSlug
  ↓
Endpoint handler

Error Handling

All errors return a consistent JSON structure:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Code	Meaning	When
`400`	Bad Request	Validation failure, missing fields
`401`	Unauthorized	Invalid / expired / missing token
`403`	Forbidden	Insufficient role or permissions
`404`	Not Found	Resource doesn't exist or not accessible
`409`	Conflict	Duplicate entry, invalid state transition
`500`	Internal Error	Server error

Auth

User registration, login, and profile management.

POST

/auth/register

Create a new account. Returns a JWT and user object. Automatically creates a personal organization and workspace.

Body Parameters

emailstringrequiredValid email address

passwordstringrequired8-128 characters

namestringDisplay name, max 100 chars

curl -X POST http://localhost:3001/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com",
  "password": "secure-pass-123",
  "name": "Jane Doe"
}'

Response201

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "email": "user@example.com",
    "name": "Jane Doe"
  }
}

POST

/auth/login

Authenticate and receive a JWT.

Body Parameters

emailstringrequiredAccount email

passwordstringrequiredAccount password

curl -X POST http://localhost:3001/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com",
  "password": "secure-pass-123"
}'

Response201

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "email": "user@example.com",
    "name": "Jane Doe",
    "pilotageRole": "owner"
  }
}

GET

/auth/me

Get the current authenticated user's profile.

curl http://localhost:3001/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{
  "user": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "email": "user@example.com",
    "name": "Jane Doe",
    "pilotageRole": "owner"
  }
}

PATCH

/auth/me

Update the current user's profile.

Body Parameters

namestringMax 100 characters

curl -X PATCH http://localhost:3001/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Smith"
}'

POST

/auth/change-password

Change the current user's password. Requires the current password for verification.

Body Parameters

currentPasswordstringrequiredCurrent password

newPasswordstringrequired8-128 characters

curl -X POST http://localhost:3001/auth/change-password \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currentPassword": "old-password",
  "newPassword": "new-secure-pass"
}'

Organizations

Organizations are the top-level container. They hold workspaces and members.

POST

/organizations

Create a new organization. The creator becomes the owner.

Body Parameters

namestringrequiredOrganization name

slugstringrequired2-60 chars, lowercase, alphanumeric + hyphens

curl -X POST http://localhost:3001/organizations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corp",
  "slug": "acme-corp"
}'

Response201

{
  "id": "665f1a2b...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "ownerId": "665f1a2b...",
  "createdAt": "2026-01-15T10:30:00Z"
}

GET

/organizations

List all organizations the current user is a member of.

curl http://localhost:3001/organizations \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f1a2b...",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "myRole": "owner"
  }
]

GET

/organizations/:orgSlug

Get a single organization by slug. Requires membership.

Path Parameters

orgSlugstringrequired

curl http://localhost:3001/organizations/acme \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{
  "id": "665f1a2b...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "ownerId": "665f1a2b...",
  "myRole": "owner"
}

PATCH

/organizations/:orgSlug

Update organization details.

Path Parameters

orgSlugstringrequired

curl -X PATCH http://localhost:3001/organizations/acme \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corporation"
}'

DELETE

/organizations/:orgSlug

Delete an organization and all its workspaces, projects, and data. Owner only.

Path Parameters

orgSlugstringrequired

curl -X DELETE http://localhost:3001/organizations/acme \
  -H "Authorization: Bearer YOUR_TOKEN"

Organization Members

GET

/organizations/:orgSlug/members

List all members of an organization with their roles.

Path Parameters

orgSlugstringrequired

curl http://localhost:3001/organizations/acme/members \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "userId": "665f1a2b...",
    "role": "owner",
    "email": "owner@acme.com"
  },
  {
    "userId": "665f1b3c...",
    "role": "member",
    "email": "dev@acme.com"
  }
]

POST

/organizations/:orgSlug/members

Add a member to the organization by email.

Path Parameters

orgSlugstringrequired

Body Parameters

emailstringrequiredEmail of the user to add

rolestringrequired"admin" or "member"

curl -X POST http://localhost:3001/organizations/acme/members \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "new-member@acme.com",
  "role": "member"
}'

PATCH

/organizations/:orgSlug/members/:userId

Update a member's role. Cannot change the owner.

Path Parameters

orgSlugstringrequired

userIdstringrequired

curl -X PATCH http://localhost:3001/organizations/acme/members/USER_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "admin"
}'

DELETE

/organizations/:orgSlug/members/:userId

Remove a member from the organization.

Path Parameters

orgSlugstringrequired

userIdstringrequired

curl -X DELETE http://localhost:3001/organizations/acme/members/USER_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Workspaces

Workspaces live inside organizations and contain projects. Each workspace has its own member list and roles.

POST

/orgs/:orgSlug/workspaces

Create a new workspace within an organization.

Path Parameters

orgSlugstringrequired

Body Parameters

namestringrequiredWorkspace name

slugstringrequired2-60 chars, lowercase

curl -X POST http://localhost:3001/orgs/acme/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Engineering",
  "slug": "engineering"
}'

GET

/orgs/:orgSlug/workspaces

List all workspaces in the organization that the user has access to.

Path Parameters

orgSlugstringrequired

curl http://localhost:3001/orgs/acme/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/orgs/:orgSlug/workspaces/:wsSlug

Get a single workspace by slug.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{
  "id": "665f2d4e...",
  "name": "Engineering",
  "slug": "engineering",
  "organizationId": "665f1a2b...",
  "ownerId": "665f1a2b...",
  "isPersonal": false,
  "myRole": "admin",
  "myPilotageRole": "owner",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

Workspace Members

POST

/orgs/:orgSlug/workspaces/:wsSlug/members/invite

Send an email invitation to join the workspace. Creates a unique invitation token.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

emailstringrequiredEmail to invite

rolestring"admin" or "member"

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/members/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "teammate@company.com",
  "role": "member"
}'

POST

/invitations/:token/accept

Accept a workspace invitation using the token from the invitation email.

Path Parameters

tokenstringrequired

curl -X POST http://localhost:3001/invitations/INVITE_TOKEN/accept \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/orgs/:orgSlug/workspaces/:wsSlug/members/:userId

Update a member's workspace role and/or pilotage role.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

userIdstringrequired

Body Parameters

rolestring"admin" or "member"

pilotageRolestring"viewer", "reviewer", or "owner"

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/members/USER_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "admin",
  "pilotageRole": "reviewer"
}'

Projects

Projects contain kanban boards with columns and cards. All project endpoints are scoped to a workspace.

POST

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

Create a new project in the workspace.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

namestringrequiredProject name

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q1 Launch"
}'

Response201

{
  "id": "665f2d4e...",
  "name": "Q1 Launch",
  "workspaceId": "665f2d4e...",
  "createdAt": "2026-03-10T10:00:00Z"
}

GET

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

List all projects in the workspace.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

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

Get a single project by ID.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

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

Update project details.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q1 Launch v2"
}'

GET

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

Get a portfolio summary of all projects with aggregated metrics.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/portfolio \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

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

List available project templates.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/templates \
  -H "Authorization: Bearer YOUR_TOKEN"

Project Import & Export

GET

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

Export a project as a complete JSON snapshot (columns, cards, metadata).

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/export \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

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

Import a project from a JSON structure. Supports up to 50 columns and 500 cards.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "project": { "name": "Imported" },
  "columns": [
    { "name": "To Do" },
    { "name": "In Progress" },
    { "name": "Done" }
  ],
  "cards": [
    {
      "title": "First task",
      "columnIndex": 0,
      "priority": "medium"
    }
  ]
}'

Project Members

GET

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

List project members.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/members \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

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

Add a member to the project by email.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/members \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@company.com"
}'

DELETE

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/members/:userId

Remove a member from the project.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

userIdstringrequired

curl -X DELETE http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/members/USER_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Columns

Columns define workflow stages on a project board. Each column has a name and an order.

POST

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

Create a new column.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/columns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "In Review"
}'

GET

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

List all columns in a project, ordered by position.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/columns \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f3e5f...",
    "name": "To Do",
    "projectId": "665f2d4e...",
    "order": 0,
    "createdAt": "2026-01-15T10:30:00Z"
  }
]

PATCH

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/columns/:columnId

Update a column's name or order.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

columnIdstringrequired

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/columns/COL_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Code Review"
}'

DELETE

/orgs/:orgSlug/workspaces/:wsSlug/projects/:projectId/columns/:columnId

Delete a column.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

columnIdstringrequired

curl -X DELETE http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/columns/COL_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{ "ok": true }

Cards

Cards are the core work items. They live in columns and support rich metadata.

GET

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

List all cards in a project (across all columns).

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f4f6a...",
    "title": "Design API endpoints",
    "description": "REST routes for billing module",
    "columnId": "665f3e5f...",
    "order": 0,
    "archived": false,
    "priority": "high",
    "dueDate": "2026-04-01T00:00:00Z",
    "assigneeId": "665f1a2b...",
    "checklist": [
      { "_id": "a1b2c3", "title": "List endpoints", "done": true, "order": 0 }
    ],
    "commentCount": 3,
    "attachmentCount": 1
  }
]

POST

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

Create a card in a specific column.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

columnIdstringrequired

Body Parameters

titlestringrequired1-500 characters

descriptionstringMax 5000 characters

prioritystringlow | medium | high

startDatestringISO date

Complex type — edit in code

dueDatestringISO date

assigneeIdstringMongoId of assignee

checklistarrayMax 100 items

Complex type — edit in code

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/columns/COL_ID/cards \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Implement billing API",
  "description": "See spec in docs",
  "priority": "high",
  "dueDate": "2026-04-01",
  "assigneeId": "665f1a2b...",
  "checklist": [
    {
      "title": "Setup routes",
      "done": false,
      "order": 0
    }
  ]
}'

PATCH

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

Update any card field. Only include fields you want to change. Set nullable fields to null to clear them.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated title",
  "columnId": "665f3e5f...",
  "order": 2,
  "priority": "medium",
  "dueDate": null,
  "archived": true
}'

DELETE

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

Permanently delete a card.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

curl -X DELETE http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{ "ok": true }

Comments

Comments on cards. Base path includes the project and card IDs.

GET

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

List all comments on a card, ordered by creation date.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/comments \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f5a7b...",
    "cardId": "665f4f6a...",
    "authorId": "665f1a2b...",
    "authorName": "Jane Doe",
    "content": "Spec looks good, let's proceed.",
    "createdAt": "2026-03-10T14:22:00Z"
  }
]

POST

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

Attachments

File attachments on cards. Max file size: 10 MB.

GET

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

List all attachments on a card.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/attachments \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f6b8c...",
    "cardId": "665f4f6a...",
    "uploadedBy": "665f1a2b...",
    "originalName": "api-spec.pdf",
    "mimeType": "application/pdf",
    "size": 245760,
    "createdAt": "2026-03-10T14:30:00Z"
  }
]

POST

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

Upload a file. Use multipart/form-data with field name 'file'.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

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

GET

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

Download an attachment. Returns the raw file stream with the correct MIME type.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

attachmentIdstringrequired

curl http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/attachments/ATT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

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

Delete an attachment.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

projectIdstringrequired

cardIdstringrequired

attachmentIdstringrequired

curl -X DELETE http://localhost:3001/orgs/acme/workspaces/eng/projects/PROJ_ID/cards/CARD_ID/attachments/ATT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Notifications

Activity-based notifications for the current user. Generated automatically when cards are created, updated, moved, assigned, or commented on.

GET

/notifications

List notifications for the current user.

Query Parameters

limitnumberMax results (default: 50)

unreadOnlystring"true" or "1" to filter unread only

curl http://localhost:3001/notifications \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f7c9d...",
    "userId": "665f1a2b...",
    "readAt": null,
    "activity": {
      "type": "card_moved",
      "actorId": "665f1b3c...",
      "meta": {
        "fromColumn": "To Do",
        "toColumn": "In Progress"
      },
      "createdAt": "2026-03-10T15:00:00Z"
    }
  }
]

GET

/notifications/count

Get unread notification count.

curl http://localhost:3001/notifications/count \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{ "count": 12 }

PATCH

/notifications/read-all

Mark all notifications as read.

curl -X PATCH http://localhost:3001/notifications/read-all \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/notifications/:id/read

Mark a single notification as read.

Path Parameters

idstringrequired

curl -X PATCH http://localhost:3001/notifications/ID/read \
  -H "Authorization: Bearer YOUR_TOKEN"

Activity Types

Type	Triggered When
`card_created`	A new card is created
`card_updated`	Card fields are modified
`card_moved`	Card moves to a different column
`card_archived`	Card is archived
`card_deleted`	Card is permanently deleted
`card_assigned`	Card assignee changes
`comment_added`	A comment is posted on a card
`member_added`	A member joins the project
`member_removed`	A member is removed

Pilotage

The strategic command center. Manages missions, priorities, todos, decisions, documentation, and AI-proposed actions. All endpoints are workspace-scoped.

GET

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/state

Get the complete pilotage state for a workspace. Same data exposed to AI agents via MCP's get_pilotage_state tool.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Query Parameters

profilestringpilotage | execution | revue (default: pilotage)

intentstringweekly_review | daily_execution | sprint_planning | context_only

detailLevelstringminimal | standard | detailed (default: standard)

curl http://localhost:3001/orgs/acme/workspaces/eng/pilotage/state \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

{
  "cycle": "v8",
  "contractVersion": 7,
  "missions": [
    {
      "id": "m-001",
      "objective": "Implement billing module",
      "module": "billing",
      "status": "in_progress",
      "blockedReason": null
    }
  ],
  "activePriorities": [...],
  "todos": [...],
  "decisions": [...],
  "activeDocs": [...],
  "usageContext": {
    "profile": "pilotage",
    "role": "owner",
    "intent": "weekly_review"
  }
}

Missions

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/missions

Create a new mission.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

objectivestringrequiredMission objective

modulestringModule name

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/missions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "objective": "Implement billing module",
  "module": "billing"
}'

PATCH

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/missions/:id

Update a mission's status or details.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

idstringrequired

Body Parameters

statusstringto_launch | in_progress | blocked | done

blockedReasonstringMax 200 chars, or null to clear

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/pilotage/missions/ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "blocked",
  "blockedReason": "Waiting on API"
}'

Priorities

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/priorities

Create a new priority.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/priorities \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Ship billing MVP",
  "module": "billing"
}'

Todos

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/todos

Create a new todo.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

labelstringrequiredTodo label

missionIdstringLink to a mission

priorityIdstringLink to a priority

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Write Stripe integration tests",
  "missionId": "m-001",
  "priorityId": "p-001"
}'

PATCH

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/todos/:id

Update a todo's status.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

idstringrequired

Body Parameters

statusstringtodo | in_progress | blocked | done

curl -X PATCH http://localhost:3001/orgs/acme/workspaces/eng/pilotage/todos/ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "done"
}'

Decisions

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/decisions

Record a strategic decision.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

titlestringrequiredDecision title

impactstringImpact description

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/decisions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Use Stripe over custom billing",
  "impact": "Reduces dev time by 3 weeks, adds 2.9% transaction fee"
}'

Active Docs

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/docs

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

titlestringrequiredDocument title

ownerstringOwner name

sourceTypestringproduct | tech | sprint | ops

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/docs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Billing API Spec v2",
  "owner": "Jane Doe",
  "sourceType": "tech"
}'

Proposed Actions (AI Review)

POST

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

Submit an AI-proposed action for human review.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Body Parameters

actionTypestringrequiredMax 100 chars

explanationstringrequiredMax 500 chars

payloadobjectOptional context data

Complex type — edit in code

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/actions/propose \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "actionType": "move_card",
  "explanation": "All subtasks complete, move to Done",
  "payload": {
    "cardId": "665f4f6a...",
    "targetColumn": "Done"
  }
}'

Response201

{
  "id": "act-001",
  "actionType": "move_card",
  "explanation": "All subtasks complete, move to Done",
  "status": "suggested",
  "payload": {
    "cardId": "665f4f6a...",
    "targetColumn": "Done"
  },
  "createdAt": "2026-03-10T15:30:00Z"
}

GET

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

List proposed actions, optionally filtered by status.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

Query Parameters

statusstringsuggested | approved | rejected | applied

curl http://localhost:3001/orgs/acme/workspaces/eng/pilotage/actions \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/:id/review

Approve or reject a proposed action.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

idstringrequired

Body Parameters

approvedbooleanrequiredtrue to approve, false to reject

reasonstringOptional, max 200 chars

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/actions/ID/review \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approved": true,
  "reason": "Looks correct"
}'

POST

/orgs/:orgSlug/workspaces/:wsSlug/pilotage/actions/:id/apply

Apply an approved action. Only works on actions with status 'approved'.

Path Parameters

orgSlugstringrequired

wsSlugstringrequired

idstringrequired

curl -X POST http://localhost:3001/orgs/acme/workspaces/eng/pilotage/actions/ID/apply \
  -H "Authorization: Bearer YOUR_TOKEN"

API Tokens

Manage Personal Access Tokens for programmatic API access. These endpoints require JWT authentication (not PAT) to prevent token escalation.

POST

/api-tokens

Create a new token. The full token value is only returned once.

Body Parameters

namestringrequiredMax 100 chars

scopesarrayDefaults to all scopes

Complex type — edit in code

expiresAtstringISO date or null for no expiry

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

Response201

{
  "id": "665f8dae...",
  "token": "synth_a1b2c3d4e5f6...",
  "name": "CI Pipeline",
  "prefix": "synth_a1b2",
  "scopes": ["projects:read", "projects:write"],
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-03-10T16:00:00Z"
}

GET

/api-tokens

List all tokens for the current user. Does not include the full token value.

curl http://localhost:3001/api-tokens \
  -H "Authorization: Bearer YOUR_TOKEN"

Response200

[
  {
    "id": "665f8dae...",
    "name": "CI Pipeline",
    "prefix": "synth_a1b2",
    "scopes": ["projects:read", "projects:write"],
    "expiresAt": "2027-01-01T00:00:00Z",
    "lastUsedAt": "2026-03-12T09:15:00Z",
    "createdAt": "2026-03-10T16:00:00Z"
  }
]

DELETE

/api-tokens/:id

Revoke a token permanently.

Path Parameters

idstringrequired

curl -X DELETE http://localhost:3001/api-tokens/ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Available Scopes

Scope	Grants Access To
`projects:read`	Read projects, columns, cards, comments, attachments
`projects:write`	Create/update/delete projects, columns, cards, comments, attachments
`pilotage:read`	Read pilotage state (missions, priorities, todos, decisions)
`pilotage:write`	Create/update missions, todos, decisions; propose actions
`notifications:read`	Read and manage notifications
`account:read`	Read user profile
`account:write`	Update user profile

Scopes

Scopes are logical work packages or phases within a project. Each scope has its own columns, cards, and views (Kanban, List, Calendar, Roadmap, Stats).

POST

/…/projects/:projectId/scopes

Create a new scope within a project.

Path Parameters

projectIdstringrequired

curl -X POST http://localhost:3001/…/projects/PROJ_ID/scopes \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/projects/:projectId/scopes

List all scopes for a project.

Path Parameters

projectIdstringrequired

curl http://localhost:3001/…/projects/PROJ_ID/scopes \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/scopes/:scopeId

Get scope details including columns and view configuration.

Path Parameters

scopeIdstringrequired

curl http://localhost:3001/…/scopes/SCOPEID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/scopes/:scopeId

Update scope name or settings.

Path Parameters

scopeIdstringrequired

curl -X PATCH http://localhost:3001/…/scopes/SCOPEID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/scopes/:scopeId

Delete a scope and all its contents.

Path Parameters

scopeIdstringrequired

curl -X DELETE http://localhost:3001/…/scopes/SCOPEID \
  -H "Authorization: Bearer YOUR_TOKEN"

Scope Views

Each scope supports 5 view types: kanban, list, calendar, roadmap, stats.

GET

/…/scopes/:scopeId/views

List available views and the currently active view.

Path Parameters

scopeIdstringrequired

curl http://localhost:3001/…/scopes/SCOPEID/views \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/scopes/:scopeId/views

Switch the active view type.

Path Parameters

scopeIdstringrequired

curl -X PATCH http://localhost:3001/…/scopes/SCOPEID/views \
  -H "Authorization: Bearer YOUR_TOKEN"

Labels

Color-coded tags for categorizing cards. Labels are defined at the project level and can be applied to any card within that project.

POST

/…/projects/:projectId/labels

Create a new label with a name and color.

Path Parameters

projectIdstringrequired

curl -X POST http://localhost:3001/…/projects/PROJ_ID/labels \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/projects/:projectId/labels

List all labels for a project.

Path Parameters

projectIdstringrequired

curl http://localhost:3001/…/projects/PROJ_ID/labels \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/labels/:labelId

Update label name or color.

Path Parameters

labelIdstringrequired

curl -X PATCH http://localhost:3001/…/labels/LABELID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/labels/:labelId

Delete a label. Removes it from all cards.

Path Parameters

labelIdstringrequired

curl -X DELETE http://localhost:3001/…/labels/LABELID \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/cards/:cardId/labels/:labelId

Add a label to a card.

Path Parameters

cardIdstringrequired

labelIdstringrequired

curl -X POST http://localhost:3001/…/cards/CARD_ID/labels/LABELID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/cards/:cardId/labels/:labelId

Remove a label from a card.

Path Parameters

cardIdstringrequired

labelIdstringrequired

curl -X DELETE http://localhost:3001/…/cards/CARD_ID/labels/LABELID \
  -H "Authorization: Bearer YOUR_TOKEN"

Custom Fields

Project-level custom metadata fields. Supported types: text, number, select, multi-select, date, boolean.

POST

/…/projects/:projectId/custom-fields

Create a custom field definition. For select/multi-select, include options array.

Path Parameters

projectIdstringrequired

curl -X POST http://localhost:3001/…/projects/PROJ_ID/custom-fields \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/projects/:projectId/custom-fields

List all custom field definitions for a project.

Path Parameters

projectIdstringrequired

curl http://localhost:3001/…/projects/PROJ_ID/custom-fields \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/custom-fields/:fieldId

Update field name, type, or options.

Path Parameters

fieldIdstringrequired

curl -X PATCH http://localhost:3001/…/custom-fields/FIELDID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/custom-fields/:fieldId

Delete a custom field. Removes values from all cards.

Path Parameters

fieldIdstringrequired

curl -X DELETE http://localhost:3001/…/custom-fields/FIELDID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/cards/:cardId/custom-fields

Set custom field values for a card. Body is an object mapping fieldId to value.

Path Parameters

cardIdstringrequired

curl -X PATCH http://localhost:3001/…/cards/CARD_ID/custom-fields \
  -H "Authorization: Bearer YOUR_TOKEN"

Card Relations

Link cards together with typed relationships: blocks / blocked_by, related_to, duplicates, parent_of.

POST

/…/cards/:cardId/relations

Create a relation between two cards. Body: { targetCardId, type }.

Path Parameters

cardIdstringrequired

curl -X POST http://localhost:3001/…/cards/CARD_ID/relations \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/cards/:cardId/relations

List all relations for a card.

Path Parameters

cardIdstringrequired

curl http://localhost:3001/…/cards/CARD_ID/relations \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/relations/:relationId

Delete a relation.

Path Parameters

relationIdstringrequired

curl -X DELETE http://localhost:3001/…/relations/RELATIONID \
  -H "Authorization: Bearer YOUR_TOKEN"

Checklists

Checklist items within a card. Progress percentage is computed automatically and displayed on the card.

POST

/…/cards/:cardId/checklist

Add a checklist item. Body: { title }.

Path Parameters

cardIdstringrequired

curl -X POST http://localhost:3001/…/cards/CARD_ID/checklist \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/cards/:cardId/checklist/:itemId

Update a checklist item (toggle checked, rename).

Path Parameters

cardIdstringrequired

itemIdstringrequired

curl -X PATCH http://localhost:3001/…/cards/CARD_ID/checklist/ITEMID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/cards/:cardId/checklist/:itemId

Delete a checklist item.

Path Parameters

cardIdstringrequired

itemIdstringrequired

curl -X DELETE http://localhost:3001/…/cards/CARD_ID/checklist/ITEMID \
  -H "Authorization: Bearer YOUR_TOKEN"

Documents

Knowledge base with 8 document types: document, spec, brief, adr, note, reference, template, spreadsheet. Documents can be scoped to organization, workspace, project, or scope level.

POST

/…/documents

Create a document. Body includes title, docType, content (TipTap JSON), and optional parentId.

curl -X POST http://localhost:3001/…/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/documents

List documents. Filter by docType, context scope, or parentId.

curl http://localhost:3001/…/documents \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/documents/:documentId

Get full document with content.

Path Parameters

documentIdstringrequired

curl http://localhost:3001/…/documents/DOCUMENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/documents/:documentId

Update document title, content, or metadata. Auto-saves supported.

Path Parameters

documentIdstringrequired

curl -X PATCH http://localhost:3001/…/documents/DOCUMENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/documents/:documentId

Delete a document.

Path Parameters

documentIdstringrequired

curl -X DELETE http://localhost:3001/…/documents/DOCUMENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

Review Workflow

Documents can be submitted for review. Statuses: draft → pending_review → approved / changes_requested.

POST

/…/documents/:documentId/submit-review

Submit a document for review.

Path Parameters

documentIdstringrequired

curl -X POST http://localhost:3001/…/documents/DOCUMENTID/submit-review \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/documents/:documentId/review

Review a document. Body: { status, notes }.

Path Parameters

documentIdstringrequired

curl -X POST http://localhost:3001/…/documents/DOCUMENTID/review \
  -H "Authorization: Bearer YOUR_TOKEN"

Agents

Workspace-scoped AI agents with configurable tools and autonomy levels. Three modes: supervised (propose + approve), autonomous (execute directly), approval (batch review).

POST

/…/agents

Create an agent. Body: name, slug, autonomyMode, tools whitelist, rate limits.

curl -X POST http://localhost:3001/…/agents \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/agents

List all agents in the workspace.

curl http://localhost:3001/…/agents \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/agents/:agentId

Get agent details and configuration.

Path Parameters

agentIdstringrequired

curl http://localhost:3001/…/agents/AGENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/agents/:agentId

Update agent configuration.

Path Parameters

agentIdstringrequired

curl -X PATCH http://localhost:3001/…/agents/AGENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/agents/:agentId

Delete an agent.

Path Parameters

agentIdstringrequired

curl -X DELETE http://localhost:3001/…/agents/AGENTID \
  -H "Authorization: Bearer YOUR_TOKEN"

Missions

Card-level AI tasks with real-time SSE streaming. Lifecycle: queued → running → awaiting_approval → completed / failed / cancelled.

POST

/…/agents/:agentId/missions

Create a mission on a card. Body: { cardId, prompt }.

Path Parameters

agentIdstringrequired

curl -X POST http://localhost:3001/…/agents/AGENTID/missions \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/agents/:agentId/missions

List missions for an agent.

Path Parameters

agentIdstringrequired

curl http://localhost:3001/…/agents/AGENTID/missions \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/missions/:missionId

Get mission details and progress.

Path Parameters

missionIdstringrequired

curl http://localhost:3001/…/missions/MISSIONID \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/missions/:missionId/cancel

Cancel a running mission.

Path Parameters

missionIdstringrequired

curl -X POST http://localhost:3001/…/missions/MISSIONID/cancel \
  -H "Authorization: Bearer YOUR_TOKEN"

Proposals

Supervised agents propose changes before execution. Each proposal contains the action to perform and can be approved or rejected.

GET

/…/missions/:missionId/proposals

List proposals for a mission.

Path Parameters

missionIdstringrequired

curl http://localhost:3001/…/missions/MISSIONID/proposals \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/proposals/:proposalId/approve

Approve a proposal. The action will be executed.

Path Parameters

proposalIdstringrequired

curl -X POST http://localhost:3001/…/proposals/PROPOSALID/approve \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/proposals/:proposalId/reject

Reject a proposal. Body: { reason }.

Path Parameters

proposalIdstringrequired

curl -X POST http://localhost:3001/…/proposals/PROPOSALID/reject \
  -H "Authorization: Bearer YOUR_TOKEN"

Automations

Project-level automation rules. 7 trigger types: task_moved, task_created, checklist_complete, due_date_reached, task_status_changed, task_assigned, task_added_to_board.

POST

/…/automations

Create an automation rule. Body: trigger, conditions (JSON), action.

curl -X POST http://localhost:3001/…/automations \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/automations

List all automation rules for a project.

curl http://localhost:3001/…/automations \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/automations/:ruleId

Get automation rule details.

Path Parameters

ruleIdstringrequired

curl http://localhost:3001/…/automations/RULEID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/automations/:ruleId

Update an automation rule.

Path Parameters

ruleIdstringrequired

curl -X PATCH http://localhost:3001/…/automations/RULEID \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/automations/:ruleId

Delete an automation rule.

Path Parameters

ruleIdstringrequired

curl -X DELETE http://localhost:3001/…/automations/RULEID \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH

/…/automations/:ruleId/toggle

Enable or disable an automation rule.

Path Parameters

ruleIdstringrequired

curl -X PATCH http://localhost:3001/…/automations/RULEID/toggle \
  -H "Authorization: Bearer YOUR_TOKEN"

Execution Traces

Every automation execution is logged with actor, target, timestamp, and result (success/failure).

GET

/…/automations/:ruleId/traces

List execution traces for an automation rule.

Path Parameters

ruleIdstringrequired

curl http://localhost:3001/…/automations/RULEID/traces \
  -H "Authorization: Bearer YOUR_TOKEN"

AI Project Wizard

Multi-stage AI-guided project creation. Stages: Framing → Refinement (adaptive questions, readiness score) → Roadmap generation → Execution (phases become columns, deliverables become cards).

POST

/…/project-drafts

Create a new project draft. Body: { name, description, contextDocuments }.

curl -X POST http://localhost:3001/…/project-drafts \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/project-drafts

List all drafts for the workspace.

curl http://localhost:3001/…/project-drafts \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/…/project-drafts/:draftId

Get draft details including current stage and questions.

Path Parameters

draftIdstringrequired

curl http://localhost:3001/…/project-drafts/DRAFTID \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/project-drafts/:draftId/refine

Submit answers to refinement questions. Returns next questions or readiness score.

Path Parameters

draftIdstringrequired

curl -X POST http://localhost:3001/…/project-drafts/DRAFTID/refine \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/project-drafts/:draftId/generate-roadmap

Generate a phased roadmap from the refinement data.

Path Parameters

draftIdstringrequired

curl -X POST http://localhost:3001/…/project-drafts/DRAFTID/generate-roadmap \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/…/project-drafts/:draftId/execute

Execute the draft: create the project with phases as columns and deliverables as cards.

Path Parameters

draftIdstringrequired

curl -X POST http://localhost:3001/…/project-drafts/DRAFTID/execute \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE

/…/project-drafts/:draftId

Delete a draft.

Path Parameters

draftIdstringrequired

curl -X DELETE http://localhost:3001/…/project-drafts/DRAFTID \
  -H "Authorization: Bearer YOUR_TOKEN"

For AI integration via MCP, see the MCP Integration guide. For a guided walkthrough, see Getting Started.