Skip to content

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

QueryFilters by
sectionSection type, for example users or product
typeBlock type, for example persona
statusempty (still a stub) or complete (past stub)
searchText 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 — value replaces the whole value.
  • PATCH /projects/{projectId}/blocks/{blockKey} · write — fields is 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

RouteScopeReturns
GET /projects/{projectId}/v3readThe canonical graph: eight groups, thirty-four entities, their blocks with body and shape
GET /projects/{projectId}/v3/orientationreadThe project's binding and state
GET /projects/{projectId}/v3/healthreadThe health report: score, findings, recommendations
GET /projects/{projectId}/v3/driftreadBroken references and rule violations
GET /projects/{projectId}/v3/orgreadWhat the project inherits from its organisation, with the drift report
GET /projects/{projectId}/v3/page-context?route=/pricingreadWhat a route is in the graph: its IA node, journey steps and glossary terms
POST /projects/{projectId}/v3/briefingreadA briefing: { "task_type", "target", "task", "budget", "format": "json" | "text" }
PATCH /projects/{projectId}/v3/maturitywriteSet a block's lifecycle: { "block_key", "maturity", "evidence" }
POST /projects/{projectId}/v3/scaffoldwriteAdd a stub for every entity that is missing; safe to repeat
POST /projects/{projectId}/v3/ingestwriteFree text (text, source) into writes, as one batch

For coding agents

RouteScopeReturns
GET /projects/{projectId}/anchorreadThe project's anchor for AGENTS.md, as markdown
GET /projects/{projectId}/design-skillreadThe 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:

RouteScopeWhat it is for
POST /episodeswrite or syncHand over something that happened: a meeting, a published post, a result. Safe to send twice
GET /profiles/{profileId}/bundle?project=…readThe part of the brain an app's profile reads, with an ETag
GET, POST /profiles/{profileId}/webhooksread, writeList or register a webhook for when that bundle changes
DELETE /profiles/{profileId}/webhooks/{webhookId}writeRemove 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

Last updated: