API Contract

The cPod backend exposes a REST API documented as an OpenAPI 3.1 specification. The spec is the authoritative source of truth for every endpoint, request/response shape, and error code in the platform.

Emulator vs Production Backend#

The cPod emulator is a fully-functional stub backend built to serve the same REST contract as the production cpod-backend. During development you point the SDK at the emulator; in production you point it at https://api.cyberpod.app. The contract is identical — the only difference is where the data lives and how tokens are issued.

Switching base URL in the SDK:

import { CpodClient } from '@cpod/sdk'
 
// Development — emulator
const dev = new CpodClient({
  apiKey: 'any-key',
  baseUrl: 'http://localhost:4000',
})
 
// Production
const prod = new CpodClient({
  apiKey: process.env.CPOD_API_KEY!,
  // baseUrl defaults to https://api.cyberpod.app
})

from cpod import CpodClient
 
# Development — emulator
dev = CpodClient(api_key="any-key", base_url="http://localhost:4000")
 
# Production
prod = CpodClient.from_env()  # reads CPOD_BASE_URL and CPOD_API_KEY

import cpod "github.com/cpod-ai/cpod-sdk-go"
 
// Development — emulator
dev := cpod.New("any-key", cpod.WithBaseURL("http://localhost:4000"))
 
// Production
prod := cpod.New(os.Getenv("CPOD_API_KEY"))

using Cpod.SDK;
 
// Development — emulator
var dev = new CpodClient("any-key", baseUrl: "http://localhost:4000");
 
// Production
var prod = new CpodClient(Environment.GetEnvironmentVariable("CPOD_API_KEY")!);

Authentication#

All endpoints except /api/v1/auth/token and /health require a Bearer token.

Obtaining a token#

curl -s http://localhost:4000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"dev","client_secret":"dev","grant_type":"client_credentials"}'
# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600}

curl -s https://api.cyberpod.app/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>",
    "grant_type": "client_credentials"
  }'
# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600}

Using the token#

GET /v1/people HTTP/1.1
Host: api.cyberpod.app
Authorization: Bearer eyJ...
Accept: application/json

The SDKs handle token acquisition and refresh automatically when you provide apiKey (SDK shorthand for the OAuth client secret).

Domain → API Prefix Mapping#

Every EDM domain has a dedicated base path. All entity CRUD operations follow the pattern GET|POST /v1/{prefix}, GET|PATCH|DELETE /v1/{prefix}/{id}.

Standard Request/Response Envelope#

Single-entity response (ApiResponse<T>)#

Every endpoint that returns a single entity wraps it in this shape:

{
  "data": { /* entity object */ },
  "meta": {
    "requestId": "req-01J...",
    "timestamp": "2026-05-22T10:00:00.000Z"
  }
}

List response (PaginatedResponse<T>)#

List endpoints (GET /v1/{prefix}) return:

{
  "data": [ /* entity objects */ ],
  "total": 1024,
  "page": 1,
  "pageSize": 50,
  "hasMore": true,
  "meta": {
    "requestId": "req-01J...",
    "timestamp": "2026-05-22T10:00:00.000Z"
  }
}

Mutation request body#

Create and update requests send a JSON body with Content-Type: application/json. Only the fields you include are applied (partial update / PATCH semantics for updates).

{
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice@acme.com",
  "type": "employee"
}

Error Codes#

All errors follow RFC 7807 Problem Detail format:

{
  "title": "Validation Error",
  "status": 422,
  "detail": "email must be a valid email address",
  "instance": "/v1/people",
  "requestId": "req-01J..."
}

Specification File#

The OpenAPI 3.1 spec lives at docs/api-contract/openapi.yaml. All schemas use JSON Schema Draft 2020-12 with additionalProperties: false.

View interactively#

npx @redocly/cli preview-docs docs/api-contract/openapi.yaml
# Opens http://localhost:8080

npx @cpod/emulator --ui
# Opens http://localhost:4000/docs

npx @stoplight/elements-dev-portal
# Point it at docs/api-contract/openapi.yaml

Contract Validation (CI)#

Every PR touching docs/api-contract/, emulator/src/routes/, or sdks/ triggers the API Contract Validation workflow (.github/workflows/api-contract.yml), which runs:

1. Spectral lint#

2. Path completeness check#

scripts/check-api-contract.mjs asserts ≥ 40 paths, ≥ 10 component schemas, OpenAPI 3.1.x, info.contact present, and every path starting with /v1/.

3. SDK alignment check#

scripts/validate-api-contract.ts compares SDK service names against OpenAPI tags and fails if any service has no corresponding tag (or vice-versa).

Keeping the Contract in Sync#

When you add a new endpoint, follow this order:

1. Emulator route — add the handler in emulator/src/routes/
2. OpenAPI spec — add the path + schema to docs/api-contract/openapi.yaml
3. SDK methods — implement the client method in all four SDKs
4. Tests — add at minimum a smoke test per SDK
5. Docs — update the relevant domain page under docs/pages/docs/domains/

Entity ID Prefixes#

All cPod entity IDs use a short kebab prefix so they are self-describing in logs:

The cpod-id-pattern Spectral rule warns when an id property is missing a pattern constraint, keeping the spec honest about ID shapes.