REST API Reference

The Cosmo REST API provides programmatic access to all Cosmo resources. All endpoints require authentication unless noted, and are scoped to the authenticated user's organization.

Base URL: https://api.cosmo.dev/api/v1

Authentication

Most endpoints require a Clerk JWT. Pass it in the Authorization header:

Authorization: Bearer <clerk_token>

Some flows issue a Cosmo JWT (via the exchange-token endpoint). Admin-only endpoints use a separate admin secret header.

Roles

Auth

Exchange Token

POST /auth/exchange-token

Exchange a Clerk JWT for a Cosmo JWT. Called by the desktop app on sign-in. Creates or syncs the user and org in Cosmo's database.

Request body:

Response:

{
  "token": "cosmo.jwt...",
  "user": { "id": "...", "name": "...", "email": "..." },
  "org": { "id": "...", "name": "...", "slug": "..." },
  "role": "OWNER",
  "onboardingCompleted": false,
  "onboardingSeeded": false
}

Refresh Token

POST /auth/refresh

Refresh an expired Cosmo JWT. There is a 7-day grace window after expiry.

Request body:

{ "token": "<expired_cosmo_jwt>" }

Response: Same shape as exchange-token.

Get Current User

GET /auth/me

Auth: Clerk JWT

Returns the authenticated user's profile, org, and role.

Mark Onboarding Complete

POST /auth/onboarding-complete

Auth: Clerk JWT

Marks the current user's onboarding as complete.

Seed Onboarding

POST /auth/seed-onboarding

Auth: Clerk JWT

Idempotent — creates the shared team, shared workspace, and sample tasks for a new org. Safe to call multiple times.

CLI Auth

GET /auth/cli-auth?port=<port>&state=<state>
GET /auth/cli-callback?port=<port>&state=<state>

Two-step CLI authentication flow. The CLI opens the first URL in a browser, which redirects to Clerk sign-in. After sign-in, Clerk redirects to the callback, which mints a Cosmo JWT and posts it back to the CLI's local HTTP server.

Organization

All org endpoints require Clerk JWT.

List Members

GET /org/members

Returns all members of the authenticated user's org.

Update Member Role

PATCH /org/members/:userId/role

Required role: OWNER

{ "role": "ADMIN" }

Remove Member

DELETE /org/members/:userId

Required role: OWNER or ADMIN

List Invites

GET /org/invites

Returns all pending invites.

Invite User

POST /org/invite

Required role: OWNER or ADMIN

{ "email": "alice@example.com", "role": "MEMBER" }

Resend Invite

POST /org/invite/:id/resend

Required role: OWNER or ADMIN

Revoke Invite

DELETE /org/invite/:id

Required role: OWNER or ADMIN

Chat

Stream Chat Response

POST /chat

Auth: Clerk JWT + quota check

Streams an LLM response as Server-Sent Events (text/event-stream). See SSE Events for the full event schema.

Request body:

Response: text/event-stream — see SSE Events.

List Models

GET /models

Auth: Clerk JWT

Returns the list of available LLM models.

Tasks

All task endpoints require Clerk JWT. Tasks are scoped to the authenticated user's org.

List Tasks

GET /tasks

Query parameters:

Get Task

GET /tasks/:id

Create Task

POST /tasks

TaskStatus values: TODO · IN_PROGRESS · DONE · CANCELLED

TaskPriority values: LOW · MEDIUM · HIGH · URGENT

When status changes to DONE, completedAt is set automatically. When changed away from DONE, it is cleared.

Update Task

PATCH /tasks/:id

Partial update — send only the fields to change.

Delete Task

DELETE /tasks/:id

Reorder Tasks

POST /tasks/reorder

Bulk-update sortOrder for drag-and-drop. Send an ordered array of task IDs — the server assigns sortOrder based on position in the array.

{ "taskIds": ["task_abc", "task_def", "task_ghi"] }

Reprioritize Tasks

POST /tasks/reprioritize

Apply AI-driven priority changes. Each change requires taskId and reason; priority and sortOrder are optional.

{
  "changes": [
    { "taskId": "task_abc", "priority": "HIGH", "reason": "Customer deadline moved up" }
  ]
}

Teams

All team endpoints require Clerk JWT.

List Teams

GET /teams

Returns all teams the current user belongs to.

Get Team

GET /teams/:id

Create Team

POST /teams

Update Team

PATCH /teams/:id

Delete Team

DELETE /teams/:id

List Team Members

GET /teams/:id/members

Add Team Member

POST /teams/:id/members

{ "userId": "user_..." }

Remove Team Member

DELETE /teams/:id/members/:userId

Workspaces

All workspace endpoints require Clerk JWT.

List Workspaces

GET /workspaces?teamId=<teamId>

Returns workspaces the current user can access. Filter by teamId to scope to a specific team.

Get Workspace

GET /workspaces/:id

Create Workspace

POST /workspaces

Update Workspace

PATCH /workspaces/:id

Delete Workspace

DELETE /workspaces/:id

Move Workspace

POST /workspaces/:id/move

Moves the workspace to another team.

{ "targetTeamId": "team_..." }

Reorder Workspaces

PUT /workspaces/order

Updates the visual sort order of workspaces for the current user.

Request body:

{
  "order": ["workspace_id_1", "workspace_id_2", "workspace_id_3"]
}

Response:

{ "success": true }

Connectors (MCP)

All connector endpoints require Clerk JWT. Connectors are scoped to the org.

List Connectors

GET /connectors

Returns all MCP connector instances for the org.

Create Connector

POST /connectors

Get Credentials

GET /connectors/:instanceId/credentials

Returns the stored credentials for a connector instance.

Update Credentials

POST /connectors/:instanceId/credentials

{ "credentials": { "apiKey": "sk-..." } }

Delete Connector

DELETE /connectors/:instanceId

Billing

Mutation endpoints additionally require the OWNER or ADMIN role.

Get Billing Status

GET /billing/status

Auth: Clerk JWT

Returns the subscription gate status — whether the org can access the product.

Response:

{
  "allowed": true,
  "plan": "STANDARD",
  "status": "TRIALING",
  "trialEndsAt": "2026-05-19T00:00:00Z"
}

Plan values: NO_PLAN · FREE · STANDARD · PREMIUM · ENTERPRISE

Status values: TRIALING · ACTIVE · PAST_DUE · CANCELED · PAUSED

Plan lifecycle: NO_PLAN → TRIALING/STANDARD (14-day trial) → ACTIVE (paid) → FREE (cancelled).

Get Subscription

GET /billing/subscription

Auth: Clerk JWT

Returns detailed subscription info.

Start Trial

POST /billing/trial

Required role: OWNER or ADMIN

Starts a 14-day Standard trial. Can only be called once per org.

Create Checkout Session

POST /billing/checkout

Required role: OWNER or ADMIN

{ "plan": "STANDARD" }

Returns a Stripe checkout session URL. Redirect the user to this URL to complete payment.

Create Portal Session

POST /billing/portal

Required role: OWNER or ADMIN

Returns a Stripe customer portal URL for managing the subscription.

Downgrade to Free

POST /billing/downgrade

Required role: OWNER or ADMIN

Cancels the active subscription and downgrades to the Free plan at the end of the billing period.

Metering & Quotas

All metering endpoints require Clerk JWT.

Get Org Usage

GET /metering/org

Returns token usage summary for the org's current billing period.

Get User Usage

GET /metering/user

Returns token usage for the current user in the current billing period.

Get Quota Status

GET /metering/quota

Returns the current user's daily quota status.

{
  "used": 45000,
  "limit": 100000,
  "remaining": 55000,
  "resetsAt": "2026-05-06T00:00:00Z"
}

Updates

Check for Updates

GET /updates/check

Auth: None (public)

Query parameters:

Returns update info if a newer version is available, or null if up to date.

{
  "version": "2026.5.1",
  "downloadUrl": "https://...",
  "releaseNotes": "...",
  "mandatory": false,
  "sha512": "...",
  "fileSizeBytes": 102400000
}

Error Responses

All error responses follow a standard shape:

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

Webhooks

Cosmo receives webhooks from Clerk and Stripe. These are internal endpoints verified by signature and not intended for direct use.