API
Endpoints
The REST endpoints for blocks, the canonical graph, briefings, export, episodes, profile bundles and webhooks, under https://www.epiccontext.com/api/v1. Every request is authenticated with an API key; writes take a reason and respect locks and versions.
All paths below are relative to https://www.epiccontext.com/api/v1 and need Authorization: Bearer eck_live_…; see API overview and authentication. The scope a route needs is noted as read or write.
Blocks
List blocks
GET /projects/{projectId}/blocks · read
| Query | Filters by |
|---|---|
section | Section type, for example users or product |
type | Block type, for example persona |
status | empty (still a stub) or complete (past stub) |
search | Text in the name, key or content |
The list includes archived blocks, with archived_at set.
{ "blocks": [{ "key": "primary-persona", "type": "persona", "name": "…", "body": "…", "value": {}, "maturity": "assumed", "section": { "type": "users", "name": "Users" } }], "total": 1 }
Get a block
GET /projects/{projectId}/blocks/{blockKey} · read
Returns { "block": {...} }, or 404 with { "error": "Block not found" }.
Create a block
POST /projects/{projectId}/blocks · write
curl -X POST "https://www.epiccontext.com/api/v1/projects/$PROJECT_ID/blocks" \
-H "Authorization: Bearer $EPICCONTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"section": "product",
"type": "glossary",
"key": "glossary-workspace",
"name": "Workspace",
"body": "A workspace is one project in the app menus.",
"reason": "The term appears in the UI but was not defined."
}'
section, type, key and name are required; value (the structured fields), body (the markdown), maturity and reason are optional. Returns 201 with { "block": {...} }. A key that exists in the section gives 409; a section that does not exist, 404; a value that fails the schema, 400 with issues.
Replace or merge a block
PUT /projects/{projectId}/blocks/{blockKey}· write —valuereplaces the whole value.PATCH /projects/{projectId}/blocks/{blockKey}· write —fieldsis merged into the value.
Both also accept body (the markdown, or null), name, maturity, expectedVersion and reason:
{
"fields": { "status": "accepted" },
"expectedVersion": 7,
"reason": "Accepted in the architecture review of 10 November."
}
Returns { "block": {...} }, with warnings when the schema had remarks or the write carried no reason. A locked block gives 403 with "code": "BLOCK_LOCKED"; a block that changed since expectedVersion gives 409; a block the project inherits from its organisation gives 409 with "code": "ORG_BLOCK" (override it instead, see Organisations and projects).
Archive a block
DELETE /projects/{projectId}/blocks/{blockKey} · write
Archives the block. Other blocks keep their references to it, so a restore has nothing to rebuild; it can be restored from the project's archive or the changes feed. Archiving ends the block's public link. A locked block refuses. Erasing a block for good is not on the API; see Deleting.
Search blocks
GET /projects/{projectId}/blocks/search?q=… · read — by name, for linking.
The graph
| Route | Scope | Returns |
|---|---|---|
GET /projects/{projectId}/v3 | read | The canonical graph: eight groups, thirty-four entities, their blocks with body and shape |
GET /projects/{projectId}/v3/orientation | read | The project's binding and state |
GET /projects/{projectId}/v3/health | read | The health report: score, findings, recommendations |
GET /projects/{projectId}/v3/drift | read | Broken references and rule violations |
GET /projects/{projectId}/v3/org | read | What the project inherits from its organisation, with the drift report |
GET /projects/{projectId}/v3/page-context?route=/pricing | read | What a route is in the graph: its IA node, journey steps and glossary terms |
POST /projects/{projectId}/v3/briefing | read | A briefing: { "task_type", "target", "task", "budget", "format": "json" | "text" } |
PATCH /projects/{projectId}/v3/maturity | write | Set a block's lifecycle: { "block_key", "maturity", "evidence" } |
POST /projects/{projectId}/v3/scaffold | write | Add a stub for every entity that is missing; safe to repeat |
POST /projects/{projectId}/v3/ingest | write | Free text (text, source) into writes, as one batch |
For coding agents
| Route | Scope | Returns |
|---|---|---|
GET /projects/{projectId}/anchor | read | The project's anchor for AGENTS.md, as markdown |
GET /projects/{projectId}/design-skill | read | The skill generated from the organisation's design system, with an ETag; 404 when there is no design system |
Export
GET /projects/{projectId}/export · read — the whole project as a ZIP (format=zip, the default) or JSON (format=json); includeDocuments=false leaves the documents out, history=true adds every earlier version with its reason. See Export.
For apps
These are described in Connecting to the brain:
| Route | Scope | What it is for |
|---|---|---|
POST /episodes | write or sync | Hand over something that happened: a meeting, a published post, a result. Safe to send twice |
GET /profiles/{profileId}/bundle?project=… | read | The part of the brain an app's profile reads, with an ETag |
GET, POST /profiles/{profileId}/webhooks | read, write | List or register a webhook for when that bundle changes |
DELETE /profiles/{profileId}/webhooks/{webhookId} | write | Remove a webhook |
Episodes
{
"external_id": "meeting-2026-11-10-roadmap",
"kind": "evidence",
"title": "Roadmap review",
"body": "What was said and decided…",
"occurred_at": "2026-11-10T09:00:00Z",
"refs": ["roadmap-2026"]
}
external_id, kind (evidence, performance or learning) and body are required. The same source and external_id again returns the existing episode with 200 and "created": false instead of a duplicate; a new one returns 201.
Webhooks
A webhook is registered with { "project": "…", "url": "https://…" } and returns its secret once (whsec_…). Deliveries are bundle.updated events, signed the Standard Webhooks way:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhook(secret: string, headers: Headers, rawBody: string): boolean {
const id = headers.get("webhook-id") ?? "";
const timestamp = headers.get("webhook-timestamp") ?? "";
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
return (headers.get("webhook-signature") ?? "")
.split(" ")
.some((sig) => sig.startsWith("v1,") && sig.length === expected.length + 3 && timingSafeEqual(Buffer.from(sig.slice(3)), Buffer.from(expected)));
}
A delivery is only sent when the bundle actually changed, and a webhook that fails twenty times in a row is switched off.
Next
- Connecting to the brain
- MCP tool reference: the same operations for AI clients.
Last updated: