# Context Canvas Agent API v1

Context Canvas exposes a read-only v1 API for external agents.

## Guarantees

- Read-only: no write endpoints exist under `/api/v1`.
- Authenticated: blueprint, policy and audit endpoints need an organization API key (`Authorization: Bearer cck_...`, created under Settings > API keys) or a signed-in session, and only return data in that organization. Other blueprints return 404. Index, docs, OpenAPI and templates are public.
- Scoped keys: `blueprints:read` for blueprint and policy endpoints, `audit:read` for `/api/v1/audit`. A missing scope returns 403 `INSUFFICIENT_SCOPE`; invalid, revoked and expired keys return 401 `INVALID_API_KEY`, `API_KEY_REVOKED` or `API_KEY_EXPIRED`.
- Versioned envelope: most responses include `apiVersion: "v1"`.
- Secret-safe defaults: sensitive setting values are redacted before returning API data.

## Endpoints

1. `GET /api/v1`  
   API index and docs pointers.
2. `GET /api/v1/openapi`  
   OpenAPI 3.1 document.
3. `GET /api/v1/docs`  
   JSON docs bundle for external clients.
4. `GET /api/v1/docs/markdown`  
   This markdown guide.
5. `GET /api/v1/templates`  
   Template catalog.
6. `GET /api/v1/blueprints`  
   Blueprints in your organization with node count and latest version. Cursor paging with `?limit=` and `?cursor=`.
7. `GET /api/v1/blueprints/{id}`  
   One blueprint with links to its graph, validation, versions and export preview.
8. `GET /api/v1/blueprints/{id}/graph`  
   The blueprint's nodes and edges with sanitized setting metadata.
9. `GET /api/v1/blueprints/{id}/validate`  
   Combined graph validation and Claude export compliance.
10. `GET /api/v1/blueprints/{id}/export/preview`  
   Sanitized export manifest. Optional `?targets=` and `?version=<number|latest|staging|production>`.
11. `GET /api/v1/blueprints/{id}/versions`  
   Published versions, newest first.
12. `GET /api/v1/blueprints/{id}/versions/{versionId}`  
   One immutable version (number or id) with its IR and source, secrets redacted.
13. `GET /api/v1/policy`  
   The organization policy the build gate enforces (validate results include its violations).
14. `GET /api/v1/audit`  
   The organization's audit log (scope `audit:read`). Filters: `category`, `targetId`, `from`, `to`, `limit`, `cursor`.

## Pack paths

A "pack" is the earlier name for a blueprint. `/api/v1/packs/templates` and `/api/v1/packs/{id}/...` answer the same requests as `/api/v1/templates` and `/api/v1/blueprints/{id}/...`. They are deprecated but keep working.

## Redaction Rules

- `SETTING` atom metadata:
  - `settingType: "environment"` -> all `environment` values become `"<redacted>"`.
  - `settingType: "mcp"` -> all `mcpServers[*].env` and `mcpServers[*].headers` values become `"<redacted>"`.
- Export preview files:
  - Every `.json` file: all values under any `env` or `headers` key are redacted, at any depth.
  - A `.json` file that fails to parse is replaced with `"<redacted>"`.

## Typical Client Flow

1. Discover capabilities from `GET /api/v1`.
2. Fetch docs from `GET /api/v1/docs` (or OpenAPI from `GET /api/v1/openapi`).
3. List blueprints with `GET /api/v1/blueprints`.
4. Pull a blueprint's graph via `GET /api/v1/blueprints/{id}/graph`.
5. Check readiness with `GET /api/v1/blueprints/{id}/validate`.
6. Consume safe exports from `GET /api/v1/blueprints/{id}/export/preview`.
7. Pin a reproducible export with `?version=` from `GET /api/v1/blueprints/{id}/versions`.