Version
1.0.0
API Reference
Read-Only Agent API v1
Machine-safe endpoints for external agents to inspect templates, graph state, validation results, and sanitized export previews. No write endpoints exist under /api/v1.
Capabilities
Read Only
Yes
Base Path
/api/v1
Endpoint Matrix
| Method | Path | Purpose | Notes |
|---|---|---|---|
GET | /api/v1 | API index with version, docs pointers, and endpoint list | - |
GET | /api/v1/openapi | OpenAPI 3.1 spec for the read-only API | - |
GET | /api/v1/docs | Complete docs bundle for external agent clients | - |
GET | /api/v1/docs/markdown | Markdown quick-reference for API consumers | - |
GET | /api/v1/templates | List the blueprint templates with summary metadata | - |
GET | /api/v1/blueprints | List blueprints in the caller's organization, newest first, with node count and latest version | Cursor paging: ?limit=1-100 (default 50) and ?cursor=<nextCursor>. |
GET | /api/v1/blueprints/{id} | Read one blueprint: counts, latest version, and links to its graph, validation, versions and export preview | - |
GET | /api/v1/blueprints/{id}/graph | Read a blueprint's graph (nodes and edges) with sensitive setting values redacted | Setting env values are always redacted in this endpoint. |
GET | /api/v1/blueprints/{id}/validate | Run graph validation plus Claude export compliance checks | - |
GET | /api/v1/blueprints/{id}/export/preview | Read export manifest with env and headers values redacted in every JSON file | Optional ?targets=claude-code,agents-md, ?version=<number|latest|staging|production> (default: the live draft), ?layout=plugin (an installable Claude Code plugin), ?marketplace=1, and ?otel=<OTLP endpoint> (telemetry settings tagged with the blueprint). |
GET | /api/v1/blueprints/{id}/versions | List published blueprint versions, newest first (number, content hash, message, time) | - |
GET | /api/v1/blueprints/{id}/versions/{versionId} | Read one immutable version (by number, id, latest, staging or production): its compiled IR and source snapshot, secrets redacted | - |
GET | /api/v1/policy | Read the organization policy the build gate applies to every blueprint | - |
GET | /api/v1/audit | Read the organization's audit log, newest first (needs the audit:read scope) | Filters: ?category, ?targetId, ?from and ?to (ISO 8601), ?limit=1-200, ?cursor=<nextCursor>. |
Pack paths
A "pack" is the earlier name for a blueprint. Each /api/v1/packs path answers the same requests as its /api/v1/blueprints (or /api/v1/templates) path and is deprecated.
| Deprecated path | Use |
|---|---|
/api/v1/packs/templates | /api/v1/templates |
/api/v1/packs/{id}/graph | /api/v1/blueprints/{id}/graph |
/api/v1/packs/{id}/validate | /api/v1/blueprints/{id}/validate |
/api/v1/packs/{id}/versions | /api/v1/blueprints/{id}/versions |
/api/v1/packs/{id}/versions/{versionId} | /api/v1/blueprints/{id}/versions/{versionId} |
/api/v1/packs/{id}/export/preview | /api/v1/blueprints/{id}/export/preview |
cURL Examples
Discover API capabilities
curl -s https://www.contextcanvas.ai/api/v1 | jq
Read docs bundle
curl -s https://www.contextcanvas.ai/api/v1/docs | jq
List blueprints in your organization
curl -s -H "Authorization: Bearer $CC_API_KEY" https://www.contextcanvas.ai/api/v1/blueprints | jq
Read sanitized blueprint graph
curl -s -H "Authorization: Bearer $CC_API_KEY" https://www.contextcanvas.ai/api/v1/blueprints/00000000-0000-0000-0000-000000000000/graph | jq
Run validation + compliance checks
curl -s -H "Authorization: Bearer $CC_API_KEY" https://www.contextcanvas.ai/api/v1/blueprints/00000000-0000-0000-0000-000000000000/validate | jq
Read sanitized export preview
curl -s -H "Authorization: Bearer $CC_API_KEY" https://www.contextcanvas.ai/api/v1/blueprints/00000000-0000-0000-0000-000000000000/export/preview | jq
Pull audit events since a time (needs audit:read)
curl -s -H "Authorization: Bearer $CC_API_KEY" "https://www.contextcanvas.ai/api/v1/audit?from=2026-09-01T00:00:00Z" | jq
Replace 00000000-0000-0000-0000-000000000000 with a blueprint id from /api/v1/blueprints.
Redaction Guarantees
- SETTING metadata with settingType=environment always redacts environment values.
- SETTING metadata with settingType=mcp redacts mcpServers[*].env values.
- SETTING metadata with settingType=mcp also redacts mcpServers[*].headers values.
- Export preview redacts every env and headers value in every JSON file; unparseable JSON files are withheld.
- Version IR and source snapshots redact every env and headers value at any depth, plus the SETTING metadata rules above.
Need product-level guidance and workflow docs? See /docs.