Context API

Context nodes, bundles, manifests, links, annotations, and feedback.

Context nodes are the knowledge that makes playbooks useful — brand guidelines, process docs, personas, examples. They can be linked together and to playbooks to form a connected knowledge graph that agents retrieve at runtime.

Endpoints

GET /context-nodes — List context nodes
POST /context-nodes — Create a context node
GET /context-nodes/:id — Get a context node
PATCH /context-nodes/:id — Update a context node
POST /context-nodes/:id/links — Link nodes together
GET /context/bundle — Get a context bundle
GET /context/manifest — Get a context manifest
GET /context/nodes/:id/follow — Follow links from a node
GET /context/updates — Get recent updates
POST /context/annotations — Create an annotation
POST /context/feedback — Submit feedback

All paths are relative to /api/v1/workspaces/{workspaceId}

List context nodes

GET /context-nodes

Query parameters

Parameter	Type	Description
`nodeType`	string	`brand`, `process`, `reference`, `domain-knowledge`, `example`, `index`
`status`	string	`live` (default, excludes archived), `archived` (archived only), or `all` (both)
`archived`	string	Deprecated, use `status`. `true` maps to `status=archived`, `false` maps to `status=live`. Passing both `archived` and `status` is a 400.
`sort`	string	Sort field
`order`	string	`asc` or `desc`

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/context-nodes?nodeType=brand" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Create a context node

POST /context-nodes

Requires editor role. Content supports markdown and [[wikilinks]] — any [[slug]] references in the content are automatically parsed into node links.

Request body

Field	Type	Required	Description
`title`	string	Yes	Node title
`description`	string	Yes	Brief summary of what this node contains
`content`	string	No	Full content (markdown)
`nodeType`	string	No	One of: `brand`, `process`, `reference`, `domain-knowledge`, `example`, `index`
`agentSummary`	string	No	Concise summary optimized for AI consumption
`importance`	number	No	0–100 ranking for retrieval priority
`readFirst`	boolean	No	Mark as essential context that should always be included
`edgeCaseOnly`	boolean	No	Only include when specifically relevant

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/context-nodes \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brand Voice Guidelines",
    "description": "Tone, vocabulary, and style rules for all customer-facing content",
    "content": "## Tone\nWarm but professional. Never corporate-speak...",
    "nodeType": "brand",
    "importance": 90,
    "readFirst": true
  }'

Get a context node

GET /context-nodes/:nodeId

Returns the full node including its incoming and outgoing links.

curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/context-nodes/NODE_ID \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Update a context node

PATCH /context-nodes/:nodeId

Updates any combination of node fields. Requires editor role.

curl -X PATCH https://patina.so/api/v1/workspaces/WORKSPACE_ID/context-nodes/NODE_ID \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "## Tone\nUpdated voice guidelines for Q2...",
    "agentSummary": "Brand voice: warm, professional, never use jargon"
  }'

Create a node link

POST /context-nodes/:nodeId/links

Creates an explicit link between two nodes (or between a playbook and a node).

Link types

Type	Meaning
`requires`	Source depends on target — target is always included
`references`	Source mentions target — target is included when relevant
`relates-to`	Loosely related — included at lower priority
`supersedes`	Source replaces target — target is deprioritized
`index-entry`	Source is an index node that catalogs target

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/context-nodes/NODE_ID/links \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetId": "TARGET_NODE_ID",
    "linkType": "references"
  }'

Get a context bundle

GET /context/bundle

Returns a playbook together with all its linked context nodes — the complete knowledge base an agent needs to execute the playbook. This is the primary retrieval endpoint for agents.

This endpoint counts as a retrieval and is metered against your plan's monthly limit.

Query parameters

Parameter	Type	Required	Description
`playbookId`	string	Yes	Playbook to retrieve context for
`mode`	string	No	`standard` (default) — controls content depth
`maxNodes`	number	No	Maximum number of context nodes to return
`includeAnnotations`	boolean	No	Include annotations (default: true)
`changedSince`	string	No	ISO timestamp — only return nodes updated after this time

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/bundle?playbookId=PLAYBOOK_ID&mode=standard&maxNodes=15" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

{
  "playbook": {
    "id": "pb_abc...",
    "title": "Blog Post Workflow",
    "latestVersion": { ... }
  },
  "nodes": [
    {
      "id": "cn_xyz...",
      "title": "Brand Voice Guidelines",
      "content": "## Tone\nWarm but professional...",
      "nodeType": "brand",
      "importance": 90
    }
  ],
  "annotations": [ ... ]
}

Get a context manifest

GET /context/manifest

Like the bundle, but returns only summaries instead of full content. Use this for progressive disclosure — get the manifest first, then fetch full nodes as needed.

This endpoint counts as a retrieval and is metered against your plan's monthly limit.

Query parameters

Parameter	Type	Required	Description
`playbookId`	string	Yes	Playbook to retrieve manifest for
`maxNodes`	number	No	Maximum nodes to include
`changedSince`	string	No	ISO timestamp for incremental sync

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/manifest?playbookId=PLAYBOOK_ID&maxNodes=10" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Follow context links

GET /context/nodes/:nodeId/follow

Returns ranked linked nodes from a starting node. Useful for traversing the knowledge graph.

Parameter	Type	Description
`linkType`	string	Filter by link type (can be repeated)
`maxNodes`	number	Maximum nodes to return

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/nodes/NODE_ID/follow?maxNodes=5" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Get recent updates

GET /context/updates

Returns context nodes that have been updated since a given timestamp. Use for incremental sync so your agent can stay up to date without re-fetching everything.

Parameter	Type	Description
`since`	string	ISO timestamp — return nodes updated after this time

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/updates?since=2025-03-01T00:00:00Z" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Create an annotation

POST /context/annotations

Annotations let agents (or humans) attach notes to playbooks, versions, or context nodes. Agents typically use agent_local scope so their notes don't pollute the shared workspace view.

Request body

Field	Type	Required	Description
`targetType`	string	Yes	`playbook`, `playbook_version`, or `context_node`
`targetId`	string	Yes	ID of the target resource
`scopeType`	string	Yes	`workspace_overlay` (visible to all) or `agent_local` (private to agent)
`title`	string	Yes	Annotation title
`content`	string	Yes	Annotation content
`source`	string	No	`agent` or `human`

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/annotations \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "context_node",
    "targetId": "NODE_ID",
    "scopeType": "agent_local",
    "title": "Outdated section",
    "content": "The pricing section references the old plan names",
    "source": "agent"
  }'

Submit feedback

POST /context/feedback

Agents can flag content quality issues. Feedback is reviewed by workspace members and helps keep context accurate over time.

Feedback types

Type	Meaning
`incorrect`	Content contains factual errors
`outdated`	Content is stale or references deprecated things
`missing-context`	Important context is absent
`helpful`	Positive signal — this content was useful
`low-signal`	Content exists but isn't adding value

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/context/feedback \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "playbook",
    "targetId": "PLAYBOOK_ID",
    "feedbackType": "outdated",
    "summary": "References deprecated API endpoints"
  }'

Next: Agents API