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, then send the token as the first message (not a URL query
# param — that would leak into proxy/access logs and Referer headers)
ws://localhost:8080/ws
> {"type":"auth","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`
`update`	`OWNER`, `ADMIN`, `MANAGER`
`manage`	`OWNER`, `ADMIN`
`delete`	`OWNER`, `ADMIN`

These are the five action gates checked by canRole (internal/api/helpers.go:438). create/update share the same tier, as do manage/delete.

Request Format

Content-Type: application/json
Body size limit: 16 MiB on the authed API surface (maxAPIBodyBytes, internal/api/middleware.go). Oversized Content-Length is rejected up front with 413; chunked/unlabelled bodies are bounded by a MaxBytesReader backstop. Individual handlers may impose a stricter cap (e.g. user preferences at 16 KB).
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
`405`	Method Not Allowed — the path exists but not for this method; the `Allow` response header lists the ones it does support
`409`	Conflict — duplicate slug, relation already exists
`429`	Too Many Requests — per-IP rate limit; `Retry-After` and `X-RateLimit-*` say how long to back off
`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. Request: no body. Response: {"status":"ok"}. Statuses: 200 healthy; 503 when the service is unavailable.

System

All system rows below are GET requests with no body. Response: the named system JSON object. Statuses: 200 success; 401 when authentication is required but missing; 403 for an admin-only surface; 500 on server failure.

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`	Auxiliary-model assignment per subsystem — `{"subsystems": […]}` with provider, model, timeout, `explicit`/`fallback`/`keeper_config` source, plus `healthy` (provider builds) and `reachable` (the model server answered; omitted when not probed)

Activity

Endpoint	Description
`GET /api/v1/journal?entry_type=peer.conversation,peer.escalation,assignment.created,assignment.running`	Cross-crew activity feed, sourced from the journal (the standalone `/api/v1/activity` aggregator was removed). Filter by `crew_id`/`agent_id`, bound with `since=`. See also the `crewship activity` CLI command.

Request: JSON for POST rows and no body for GET; response: the operation’s JSON result. Statuses: 200/202 on success; 400 invalid input; 401 when auth is required; 403 when disabled or unauthorized.

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

Request: CSRF/session cookies as required by the browser flow; otherwise no JSON body. Response: NextAuth JSON or redirect. Statuses: 200 success; 401 invalid credentials/session; 403 CSRF/origin failure; 405 wrong method.

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

Request: JSON for setup/complete and no body for status. Response: wizard state or completion JSON. Statuses: 200 success; 400 invalid step; 401 unauthenticated; 500 server failure.

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 (ADMIN / OWNER)

Request: no body for these GET routes. Response: the resource JSON described in each row. Statuses: 200 success; 403 insufficient admin role; 500 server failure.

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
`GET /api/v1/admin/health`	Process, database, disk, encryption-key, and log-level health snapshot (ADMIN/OWNER)
`GET /api/v1/admin/log-level`	Read live and baseline log levels (ADMIN/OWNER)
`PUT /api/v1/admin/log-level`	Set a live log level with optional TTL (ADMIN/OWNER)
`GET /api/v1/admin/legacy-resources`	Detect orphaned pre-C1 Docker resources (ADMIN/OWNER)
`GET /api/v1/admin/rate-limits`	List instance-wide limiter states (ADMIN/OWNER)
`PUT /api/v1/admin/rate-limits/{key}`	Override one limiter (ADMIN/OWNER)
`DELETE /api/v1/admin/rate-limits/{key}`	Reset one limiter to its default (ADMIN/OWNER)

All rows above take no request body and return JSON. The health, legacy, and rate-limit reads return 200 on success; admin authorization failures return 403 (and 401 when workspace authentication is absent). The rate-limit mutation returns 400 for invalid values, 404 for an unknown key, and 503 when its configuration store is unavailable. See the Admin API for complete response shapes.

Audit

Request: optional query filters, no body. Response: paginated audit JSON. Statuses: 200 success; 403 missing manage permission.

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

Request: optional query filters, no body. Response: workspace-scoped run list. Statuses: 200 success; 401 unauthenticated; 403 forbidden.

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

Workspaces

Request: JSON for mutation rows and no body for GET; response: workspace or membership JSON. Statuses: 200/201 on success; 400 invalid input; 401 unauthenticated; 403 insufficient role; 404 unknown workspace.

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 (ADMIN / OWNER)

​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 (ADMIN / OWNER)

Audit

Runs

Workspaces