SO1 Control Plane

API Documentation

Complete endpoint reference for the SO1 Control Plane API. All /api/* routes require a valid Clerk JWT in the Authorization: Bearer <token> header.

Authentication

This API uses Clerk for authentication. Protected endpoints expect a bearer token obtained from the SO1 Console session. Tokens are verified server-side against Clerk's JWKS endpoint.

$ curl -H "Authorization: Bearer $CLERK_TOKEN" \
    https://mission.so1.io/api/auth/session

Error Envelope

All error responses follow a consistent envelope structure for machine-parseable error handling:

{
  "requestId": "a1be2b66-89c1-...",
  "error": {
    "code": "NOT_FOUND",
    "message": "Endpoint not found",
    "details": { ... }
  }
}

Endpoints

Method Path Description Auth
GET / Landing page (this service's root) Public
GET /health Machine-readable health check for orchestrators Public
GET /status Human-readable system status dashboard Public
GET /docs This API documentation page Public
GET /api/auth/session Return authenticated user session details JWT
GET /api/content/clusters List all content clusters with summaries JWT
GET /api/content/clusters/:clusterId Get cluster config and JSON schema JWT
GET /api/content/:clusterId List items in a content cluster (paginated) JWT
GET /api/content/:clusterId/:itemId Get a single content item with raw content JWT
POST /api/content/:clusterId Create a new content item JWT
PUT /api/content/:clusterId/:itemId Update a content item (optimistic locking via SHA) JWT
DELETE /api/content/:clusterId/:itemId Delete a content item JWT
GET /api/content/:clusterId/:itemId/history Get version history for a content item JWT
POST /api/content/:clusterId/validate Validate content against cluster schema JWT
GET /api/catalog/repos List GitHub repositories in the organisation JWT
GET /api/workflows List n8n workflows JWT
POST /api/jobs Create a long-running job JWT
GET /api/jobs/:jobId Get job status and logs JWT
GET /api/mcp/registry List registered MCP tools JWT

Rate Limits & Headers

Header Description
X-Request-Id Unique identifier for each request — use for support and tracing
Authorization Bearer <clerk_jwt> — required for /api/* routes
Content-Type application/json for request and response bodies