1. Hosts & auth at a glance

2. Discovery

Public, no auth. Cached for 5 minutes (CloudFront).

3. OAuth 2.1 (PKCE + DCR)

Authorization Code grant with PKCE. Public clients (no secret). Dynamic Client Registration per RFC 7591. Project pinning per RFC 8707 (resource indicators).

curl -X POST https://agents.cmscaddie.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"My MCP Client","redirect_uris":["http://localhost:33333/cb"]}'

# authorization_code
curl -X POST https://agents.cmscaddie.com/oauth/token \
  -d 'grant_type=authorization_code&code=<code>&client_id=<id>&redirect_uri=<uri>&code_verifier=<verifier>'

# refresh_token (returns new access + rotated refresh)
curl -X POST https://agents.cmscaddie.com/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=<cmsr_...>&client_id=<id>'

4. MCP (Model Context Protocol)

Streamable HTTP transport. JSON-RPC 2.0 envelope. The server advertises tools auto-generated from the manifest, so new agent endpoints become MCP tools without configuration changes.

curl -X POST https://mcp.cmscaddie.com \
  -H 'Authorization: Bearer cmst_...' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

5. Agent API

All endpoints take Authorization: Bearer <cmsk_... OR cmst_...>. The path's {project} must be one of the projects this token's grants map covers, with the required scope granted on that project. Required scope on each endpoint is shown in the badge.

5a. Groups

5b. Content

curl -X POST https://agents.cmscaddie.com/projects/$P/groups/$G/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Hello","slug":"hello","published":"999901010000","body":"<p>…</p>"}'

5c. Files

curl -X POST https://agents.cmscaddie.com/projects/$P/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"spec.pdf","content_type":"application/pdf"}'

6. Programmatic API (API key)

Long-standing endpoints on api.cmscaddie.com for scripts and integrations using a project's API key (managed under Human API Keys in project settings). These predate the agent surface and are kept for backward compatibility.

7. Conventions

Idempotency

Every write on the agent surface accepts an Idempotency-Key header (recommended: a UUID per logical request). Replays with the same key+body return the cached response. Replays with a different body return 409 conflict. TTL: 24h.

Dry-run

Append ?dry_run=true to any agent write to validate and preview the would-be result without persisting.

Request IDs

Send X-Request-ID if you want to correlate; otherwise the server generates one. The id is echoed in responses (X-Request-ID header and data.request_id / error.request_id) and audit logs.

Content field schema (CRITICAL)

Every content item is shaped:

{
  "published": "YYYYMMDDHHMM",
  "fields": {
    "<field_slug>": { "name": "...", "type": "...", "value": "..." },
    ...
  }
}

Each entry under fields must be a {name, type, value} dict keyed by the field's slug. Bare strings (e.g. "title": "Hello") silently produce broken items. Discover the slugs and types per group via GET /projects/{project}/groups — each group's fields array describes them. Updates follow the same schema; when patching one field, send the full {name, type, value} object for that slug. Field types: plain-text, html, number, image, video, audio, file, code, multiple-files, content::<group_id>. Image/video/file types may include alt.

Publish semantics

Error envelope

{
  "error": {
    "code": "bad_request|unauthorized|forbidden|not_found|conflict|rate_limited|internal|upstream_unavailable",
    "message": "human-readable",
    "retryable": true|false,
    "request_id": "uuid",
    "details": { ... }      // optional, code-specific
  }
}

Success envelope

{ "data": { ... }, "request_id": "uuid" }