API Overview - Crewship

The Crewship REST API is a single versioned surface under /api/v1/ that drives every workspace, crew, agent, and credential operation. This page covers the cross-cutting conventions — base URL, the five authentication methods, RBAC roles, request/response format, pagination, and the RFC 7807 error shape — then links out to each resource group. Real-time updates and inbound triggers ride alongside REST over WebSocket and Webhooks.

Base URL

http://<host>:8080/api/v1/

All endpoints are prefixed with /api/v1/ unless otherwise noted. Exceptions:

Health check: GET /api/health
NextAuth endpoints: /api/auth/*
WebSocket upgrade: GET /ws

Authentication

Crewship supports five authentication methods depending on the context. The web UI authenticates via JWT session tokens stored in HTTP-only cookies. The Go backend validates these tokens directly (no external NextAuth server required).

Cookie Name	Condition
`authjs.session-token`	HTTP connections
`__Secure-authjs.session-token`	HTTPS connections

Tokens are set by the POST /api/auth/callback/credentials login endpoint and expire after 30 days.

2. CLI Token (Programmatic)

CLI tokens are long-lived bearer tokens prefixed with crewship_cli_. Create them via the API or CLI:

# Create a CLI token
POST /api/v1/auth/cli-token

# Use in API calls
curl -H "Authorization: Bearer crewship_cli_xxxxx" \
  http://localhost:8080/api/v1/crews?workspace_id=<id>

Endpoint	Method	Description
`POST /api/v1/auth/cli-token`	POST	Create a new CLI token
`GET /api/v1/auth/cli-token/validate`	GET	Validate the current token
`GET /api/v1/auth/cli-tokens`	GET	List all CLI tokens for the user
`DELETE /api/v1/auth/cli-tokens/{tokenId}`	DELETE	Revoke a CLI token

3. WebSocket Token (Real-time)

Short-lived JWT tokens for establishing WebSocket connections.

# Get a WS token (requires session or CLI auth)
GET /api/v1/ws-token

# Connect
ws://localhost:8080/ws?token=<jwt>

4. Internal Token (IPC)

Used by the crewshipd sidecar process for internal communication over Unix socket. Passed via X-Internal-Token header. Not available to external clients.

5. Webhook Secret (Inbound)

Per-agent HMAC secrets for authenticating inbound webhook triggers:

POST /api/v1/webhooks/{crewId}/{agentId}/trigger
Header: X-Webhook-Secret: <per-agent-secret>

Authorization (RBAC)

Workspace membership is required for all workspace-scoped endpoints. The workspace_id query parameter (or {workspaceId} path parameter) identifies the workspace context.

Role	Permissions
`OWNER`	Full access, can manage workspace settings and members
`ADMIN`	Can create, update, delete resources; manage credentials
`MANAGER`	Can create and update resources
`MEMBER`	Read-only access
`VIEWER`	Read-only access (lowest tier)

Permission mapping:

Action	Required Roles
`read`	Any authenticated member
`create`	`OWNER`, `ADMIN`, `MANAGER`
`manage`	`OWNER`, `ADMIN`

Request Format

Content-Type: application/json
Body size limit: 1 MB
Timestamps: ISO 8601 / RFC 3339 in UTC (e.g., 2024-01-15T10:30:00Z)
IDs: CUID strings (e.g., cm1a2b3c4d5e6f7g8h9i)
Slugs: Lowercase alphanumeric with hyphens, 2-50 characters (regex: ^[a-z0-9][a-z0-9_-]*$)
Soft delete: DELETE endpoints set deleted_at rather than removing rows (credentials, crews, agents)

Pagination

List endpoints use offset-based pagination:

Parameter	Type	Default	Description
`limit`	integer	20 or 50	Maximum items per page (max 100)
`offset`	integer	0	Number of items to skip

GET /api/v1/missions?workspace_id=ws123&limit=20&offset=40

Response is a JSON array of items. There is no envelope — the array is returned directly.

Error Format

Errors use RFC 7807 Problem Details where supported:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "name must be 2-100 characters",
  "instance": "/api/v1/crews"
}

Some older endpoints return a simpler format:

{
  "error": "Unauthorized"
}

Common Status Codes

Code	Meaning
`200`	Success
`201`	Created
`204`	No Content (successful delete)
`400`	Bad Request — validation error
`401`	Unauthorized — missing or invalid token
`402`	Payment Required — license limit exceeded
`403`	Forbidden — insufficient role
`404`	Not Found
`409`	Conflict — duplicate slug, relation already exists
`500`	Internal Server Error

Communication Layers

Layer	Transport	Purpose
REST API	HTTP	CRUD operations, management, auth
WebSocket	WS	Real-time log streaming, chat, event broadcasting
Webhooks	HTTP (inbound)	External triggers (GitHub, Grafana, etc.)
IPC	HTTP over Unix socket	Internal sidecar communication

Endpoint Groups

Crews

CRUD for crews, members, container config, network policies.

Agents

CRUD for agents, skills, credentials, chats, runs, persona, hire/rehire.

Missions

Mission lifecycle, tasks, start/restart/resume/clone, metrics.

Issues

Issue tracking, labels, comments, relations, activity, projects.

Credentials

Credential vault CRUD, testing, agent assignment.

Skills

Skill marketplace, import, workflow templates, crew templates.

Integrations

MCP server integrations at workspace/crew/agent level, OAuth flow.

Webhooks

Inbound webhook trigger endpoint.

WebSocket

Real-time channels, subscriptions, chat, event types.

Connectors

Curated connector catalog — browse, verify credentials, install.

Feature Flags

Feature flag CRUD with percentage rollout and per-workspace overrides.

Instance Settings

Instance-wide settings with sensitive-value redaction and protected keys.

Policies

Per-crew autonomy levels and behavior modes.

Privacy

GDPR peer-card access — view, purge, consent / opt-out.

Slash Commands

Capability-filtered slash-command catalog for the composer and CLI.

Additional Endpoints

These endpoints are documented here for completeness but do not have dedicated pages — health, system status, auth, onboarding, admin, audit, runs, and workspaces.

Health Check

GET /api/health

No authentication required. Returns {"status": "ok"} with HTTP 200.

System

Endpoint	Description
`GET /api/v1/system/runtime`	Runtime info (Go version, uptime, etc.)
`GET /api/v1/system/license`	License status and limits
`GET /api/v1/system/keeper`	Keeper (credential access control) status
`GET /api/v1/crewshipd`	Crewshipd process health and status
`GET /api/v1/system/aux-status`	Resolved auxiliary-model assignment per slot (provider, model, timeout, `explicit`/`fallback` source)

Activity

Endpoint	Description
`GET /api/v1/activity`	Cross-crew activity feed (assignments, peer conversations, escalations). Supports `crew_id` and `limit` query parameters. See also `crewship activity` CLI command.

Endpoint	Auth	Description
`POST /api/v1/bootstrap`	None	Bootstrap first user (empty instance)
`POST /api/v1/auth/signup`	None	Register a new user (when `CREWSHIP_ALLOW_SIGNUP=true`)
`GET /api/v1/ws-token`	Required	Get short-lived WebSocket JWT

NextAuth Compatibility

Endpoint	Description
`GET /api/auth/csrf`	CSRF token
`GET /api/auth/providers`	Available auth providers
`GET /api/auth/session`	Current session
`POST /api/auth/callback/credentials`	Login with email/password
`POST /api/auth/token/refresh`	Refresh the session token (NextAuth-compatible token rotation)
`GET /api/auth/signin`	Sign-in page redirect
`POST /api/auth/signout`	Sign out (clears cookie)
`GET /api/auth/error`	NextAuth error page redirect

Onboarding

Endpoint	Description
`GET /api/v1/onboarding/status`	Check onboarding completion status
`POST /api/v1/onboarding/complete`	Mark onboarding as complete
`POST /api/v1/onboarding/setup`	Run guided setup

Admin (OWNER only)

Endpoint	Description
`GET /api/v1/admin/stats`	Aggregate counts for the current workspace (workspaces always 1, users, agents, running)
`GET /api/v1/admin/users`	List members of the current workspace
`GET /api/v1/admin/workspaces`	Return the current workspace with member/agent/crew counts
`GET /api/v1/admin/keeper/requests`	Keeper access request log

Audit

Endpoint	Description
`GET /api/v1/audit`	Audit log (workspace-scoped, requires manage role)
`GET /api/v1/mcp-tool-calls`	MCP tool call audit trail

Runs

Endpoint	Description
`GET /api/v1/runs`	List agent runs (workspace-scoped)

Workspaces

Endpoint	Method	Description
`GET /api/v1/workspaces`	GET	List user’s workspaces
`POST /api/v1/workspaces`	POST	Create a workspace
`GET /api/v1/workspaces/{workspaceId}`	GET	Get workspace details
`PATCH /api/v1/workspaces/{workspaceId}`	PATCH	Update workspace
`GET /api/v1/workspaces/{workspaceId}/members`	GET	List workspace members
`POST /api/v1/workspaces/{workspaceId}/members`	POST	Add a member
`DELETE /api/v1/workspaces/{workspaceId}/members/{memberId}`	DELETE	Remove a member
`GET /api/v1/workspaces/{workspaceId}/invitations`	GET	List invitations
`POST /api/v1/workspaces/{workspaceId}/invitations`	POST	Create invitation

​Base URL

​Authentication

​1. Session Cookie (Browser)

​2. CLI Token (Programmatic)

​3. WebSocket Token (Real-time)

​4. Internal Token (IPC)

​5. Webhook Secret (Inbound)

​Authorization (RBAC)

​Request Format

​Pagination

​Error Format

​Common Status Codes

​Communication Layers

​Endpoint Groups

Crews

Agents

Missions

Issues

Credentials

Skills

Integrations

Webhooks

WebSocket

Connectors

Feature Flags

Instance Settings

Policies

Privacy

Slash Commands

​Additional Endpoints

​Health Check

​System

​Activity

​Auth / Signup

​NextAuth Compatibility

​Onboarding

​Admin (OWNER only)

​Audit

​Runs

​Workspaces

Base URL

Authentication

1. Session Cookie (Browser)

2. CLI Token (Programmatic)

3. WebSocket Token (Real-time)

4. Internal Token (IPC)

5. Webhook Secret (Inbound)

Authorization (RBAC)

Request Format

Pagination

Error Format

Common Status Codes

Communication Layers

Endpoint Groups

Additional Endpoints

Health Check

System

Activity

Auth / Signup

NextAuth Compatibility

Onboarding

Admin (OWNER only)

Audit

Runs

Workspaces