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 '@zysec-ai/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/ZySec-AI/cpod-sdk/sdks/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 /api/v1/people/persons 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 9457 Problem Details format:

{
  "title": "Validation Error",
  "status": 422,
  "detail": "email must be a valid email address",
  "instance": "/api/v1/people/persons",
  "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.

Groups & Permissions API#

All endpoints require Authorization: Bearer <token>. Access rules:

Create group#

POST /api/v1/groups
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "display_name": "CRM Writers",
  "app_id": "app-crm-sync-58d93289",   // optional: scope to an app
  "description": "Can write people records"   // optional
}

Response (201):

{
  "id": "grp_019f4824-...",
  "display_name": "CRM Writers",
  "app_id": "app-crm-sync-58d93289",
  "tenant_id": "tnt_global",
  "members": [],
  "member_details": []
}

List groups#

GET /api/v1/groups
Authorization: Bearer <token>

Returns groups based on access rules above. Each group includes members and app_id.

Get group#

GET /api/v1/groups/{group_id}
Authorization: Bearer <token>

Update group#

PATCH /api/v1/groups/{group_id}
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "display_name": "Updated Name",
  "description": "Updated description"
}

Delete group#

DELETE /api/v1/groups/{group_id}
Authorization: Bearer <token>

Add member#

POST /api/v1/groups/{group_id}/members
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "user_id": "usr_711484e0-..."
}

Remove member#

DELETE /api/v1/groups/{group_id}/members/{user_id}
Authorization: Bearer <token>

Set group permissions#

Grants the group { domain: [operations] } permissions. Operations: read, write (where write = create + update + delete).

PUT /api/v1/groups/{group_id}/permissions
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "permissions": {
    "people": ["read", "write"],
    "contracts": ["read"],
    "helpdesk": ["read", "write"]
  }
}

Response:

{
  "group_id": "grp_019f4824-...",
  "permissions": {
    "people": ["read", "write"],
    "contracts": ["read"],
    "helpdesk": ["read", "write"]
  }
}

Get group permissions#

GET /api/v1/groups/{group_id}/permissions
Authorization: Bearer <token>

Delete all group permissions#

DELETE /api/v1/groups/{group_id}/permissions
Authorization: Bearer <token>

Get user effective permissions#

Returns the merged permissions from all groups the user belongs to, optionally filtered by app_id. This is what the middleware calls internally when X-App-Id is present.

GET /api/v1/users/{user_id}/permissions
Authorization: Bearer <token>

With app_id filter (same endpoint, control-plane internal):

GET /api/v1/users/{user_id}/effective-permissions?app_id=app-crm-sync

Response:

{
  "permissions": {
    "people": ["read", "write"],
    "contracts": ["read"]
  }
}

Permission enforcement at runtime#

When an app sends a request with X-App-Id: