API Overview¶

Base URL¶

Production:  https://api.substrate.example.com/api/v1
Development: http://localhost:8000/api/v1

Authentication¶

The master API contract includes browser, automation, webhook, and internal surfaces. Browser-facing routes use the frontend contract; automation consumers should use the automation contract.

Authenticated routes use one of:

1. JWT Bearer Token (Frontend)¶

Authorization: Bearer <jwt-token>

Obtain via OIDC authentication flow with Keycloak.

2. API Key (Automation)¶

X-API-Key: <api-key>

Create and manage API tokens via /auth/tokens.

Response Format¶

Success Response¶

{
  "data": { ... },
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

Error Response¶

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Community not found: platform",
    "detail": { "resource": "community", "id": "platform" }
  }
}

HTTP Status Codes¶

Code	Meaning
200	OK — Successful GET, PATCH
201	Created — Successful POST
204	No Content — Successful DELETE
400	Bad Request — Validation error
401	Unauthorized — Missing/invalid auth
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
422	Unprocessable Entity — Schema validation failed
500	Internal Server Error — Unexpected error

Pagination¶

List endpoints support pagination via query parameters:

GET /api/v1/communities?offset=0&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20,
    "has_more": true
  }
}

Rate Limiting¶

API requests are rate-limited per authentication method:

Method	Limit
JWT Bearer	1000 requests/minute
API Key	100 requests/minute

Rate limit headers included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Codes¶

Common error codes by category:

Authentication (401)¶

Code	Description
`TOKEN_EXPIRED`	JWT token has expired
`TOKEN_INVALID`	JWT token is malformed
`API_KEY_INVALID`	API key is invalid or revoked
`MISSING_AUTHORIZATION`	No auth header provided

Resources (404)¶

Code	Description
`COMMUNITY_NOT_FOUND`	Community doesn't exist
`POLICY_NOT_FOUND`	Policy doesn't exist
`USER_NOT_FOUND`	User doesn't exist

Validation (422)¶

Code	Description
`VALIDATION_ERROR`	Request body validation failed
`INVALID_JSON`	Request body is not valid JSON
`MISSING_REQUIRED_FIELD`	Required field not provided

Client Groups¶

Endpoints are tagged with x-substrate-client-group for derived contract generation:

frontend-session — Browser-facing session routes
automation — Service-account and scripted administration routes
webhook — Inbound webhook receivers
internal — Operational platform routes

SDK Generation¶

TypeScript¶

./api/generate-types.sh

The UI types are generated from api/openapi.frontend.yml.

Python¶

pip install openapi-python-client
openapi-python-client generate --url https://api.substrate.example.com/openapi.json

Versioning¶

API versioning is URL-based:

/api/v1/...    # Current version
/api/v2/...    # Future versions

The OpenAPI specification is the source of truth for API contracts.