Hook API

The Hook API is a per-cache JSON REST API. It lets external systems read, write, and search a specific cache using a scoped Bearer token. Use it to integrate ContextCache with scripts, back-end services, or any tool that speaks HTTP.

Every request includes an authorization header with a key created in the dashboard, and the target cache ID in the URL path:

Authorization: Bearer <api-key>
GET /api/hooks/{cacheId}/...

The sections below explain how to create a key, then document each route.

Getting a key

Hook API keys are created per cache. Open the dashboard, expand Caches in the sidebar, select the cache you want to grant access to, then choose Settings. The Hook API keys section lets cache admins create and revoke keys.

Choose a scope that matches how the caller will use the API:

read for listing and searching content.
write to create or change chunks and links.
admin to enqueue automation jobs.

Only cache admins can create or revoke keys. When a key is created, the full secret appears only once. Copy it immediately and store it in a secrets manager or environment variable. If a key is lost, revoke it and issue a new one.

Dashboard: Cache settings with Hook API keys — Bearer usage hint, Create key, and table with name, prefix, scope, last used, and Revoke. — Hook API keys in Dashboard → Caches → Settings (example).

GETread

/api/hooks/{cacheId}/chunks

List chunks

Returns root-level chunks when parentId is omitted. With parentId, returns direct children of that chunk in this cache.

Parameters

parentIdstring (query)When set, list children of this parent chunk UUID.

Request

cURL

curl -sS "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY"
# Append ?parentId=<uuid> to list children of a parent chunk.

Response200

JSON

{
  "chunks": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "title": "Inbox",
      "kind": "database",
      "metadata": {}
    }
  ]
}

POSTwrite

/api/hooks/{cacheId}/chunks

Create a chunk

Creates a chunk in this cache. At least one of title or content must be non-empty after trim. If parentId is null or omitted, the server places the row under the reserved Inbox database when one exists (source metadata is set to hook).

Parameters

titlestringTitle (required together with content: at least one non-empty).

contentstringBody text; behavior depends on parent (e.g. inbox row vs document).

parentIdstring | nullParent chunk UUID, or null for default inbox placement.

Request

cURL

curl -X POST "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting notes",
    "content": "Discussed Q2 roadmap."
  }'

Response201

JSON

{
  "id": "22222222-2222-4222-8222-222222222222"
}

GETread

/api/hooks/{cacheId}/chunks/{chunkId}

Get a chunk

Loads chunk fields (id, title, content) plus outbound and inbound links for this chunk.

Parameters

No parameters.

Request

cURL

curl -sS "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks/{chunkId}" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY"

Response200

JSON

{
  "chunk": {
    "id": "22222222-2222-4222-8222-222222222222",
    "title": "Meeting notes",
    "content": "Discussed Q2 roadmap."
  },
  "links": {
    "outbound": [],
    "inbound": []
  }
}

PATCHwrite

/api/hooks/{cacheId}/chunks/{chunkId}

Update a chunk

Updates title and/or content. At least one field must be present; empty updates return 400.

Parameters

titlestringNew title (optional).

contentstringNew content (optional).

Request

cURL

curl -X PATCH "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks/{chunkId}" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Meeting notes (edited)" }'

Response200

JSON

{ "ok": true }

DELETEwrite

/api/hooks/{cacheId}/chunks/{chunkId}

Delete a chunk

Deletes a chunk with no children. System databases and chunks with nested items return 400.

Parameters

No parameters.

Request

cURL

curl -X DELETE "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks/{chunkId}" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Response204

No body

204 No Content — empty response body.

POSTwrite

/api/hooks/{cacheId}/chunks/{chunkId}/move

Move a chunk

Sets parent to newParentId, or null for a root-level chunk. Cannot move the system Inbox database.

Parameters

newParentIdstring | nullParent UUID, or null / omitted for root.

Request

cURL

curl -X POST "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/chunks/{chunkId}/move" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "newParentId": null }'

Response200

JSON

{ "ok": true }

POSTread

/api/hooks/{cacheId}/search

Semantic search

Vector search over chunks with embeddings. query is required. limit is clamped between 1 and 24 (default 8). Lower distance means more similar.

Parameters

querystringrequiredNatural language query (non-empty after trim).

limitintegerMax results (1–24, default 8).

Request

cURL

curl -X POST "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/search" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "roadmap", "limit": 8 }'

Response200

JSON

{
  "results": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "title": "Meeting notes",
      "content": "Discussed Q2 roadmap.",
      "distance": 0.21
    }
  ]
}

GETread

/api/hooks/{cacheId}/inbox

List inbox rows

Returns children of the reserved Inbox database for this cache.

Parameters

No parameters.

Request

cURL

curl -sS "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/inbox" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY"

Response200

JSON

{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "title": "Email: Re: Q2",
      "kind": "database_row",
      "contentPreview": "…",
      "createdAt": "2026-04-07T12:00:00.000Z"
    }
  ]
}

POSTwrite

/api/hooks/{cacheId}/links

Create a link

Creates a directed link between two chunks in this cache. Duplicate or self-links return 400.

Parameters

sourceIdstringrequiredSource chunk UUID.

targetIdstringrequiredTarget chunk UUID.

labelstring | nullOptional link label.

Request

cURL

curl -X POST "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/links" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "22222222-2222-4222-8222-222222222222",
    "targetId": "44444444-4444-4444-8444-444444444444",
    "label": "relates_to"
  }'

Response201

JSON

{
  "id": "55555555-5555-4555-8555-555555555555"
}

GETread

/api/hooks/{cacheId}/jobs

List jobs

Returns up to 30 most recent automation jobs for this cache (newest first).

Parameters

No parameters.

Request

cURL

curl -sS "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/jobs" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY"

Response200

JSON

{
  "jobs": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "cacheId": "{cacheId}",
      "jobType": "re_embed",
      "status": "completed",
      "targetChunkId": null,
      "scheduleId": null,
      "error": null,
      "result": null,
      "triggeredBy": null,
      "startedAt": "2026-04-07T12:01:00.000Z",
      "completedAt": "2026-04-07T12:02:00.000Z",
      "createdAt": "2026-04-07T12:00:00.000Z"
    }
  ]
}

POSTadmin

/api/hooks/{cacheId}/jobs

Enqueue a job

Requires an admin-scoped key. jobType must be a known automation slug. Optional targetChunkId must reference a chunk in this cache. Config is not accepted on this route — the worker resolves configuration server-side.

Parameters

jobTypestringrequiredAutomation slug (e.g. blueprint_run, re_embed).

targetChunkIdstring | nullOptional chunk UUID for job context.

Request

cURL

curl -X POST "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/jobs" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobType": "blueprint_run", "targetChunkId": null }'

Response201

JSON

{
  "id": "77777777-7777-4777-8777-777777777777"
}

GETread

/api/hooks/{cacheId}/jobs/{jobId}

Get a job

Returns a single job if it exists and belongs to this cache.

Parameters

No parameters.

Request

cURL

curl -sS "https://YOUR_APP_ORIGIN/api/hooks/{cacheId}/jobs/{jobId}" \
  -H "Authorization: Bearer $CC_HOOK_API_KEY"

Response200

JSON

{
  "job": {
    "id": "66666666-6666-4666-8666-666666666666",
    "cacheId": "{cacheId}",
    "jobType": "re_embed",
    "status": "running",
    "targetChunkId": null,
    "scheduleId": null,
    "error": null,
    "result": null,
    "triggeredBy": null,
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2026-04-07T12:00:00.000Z"
  }
}

Hook API

Introduction

Getting a key

List chunks

Parameters

Request

Create a chunk

Parameters

Request

Get a chunk

Parameters

Request

Update a chunk

Parameters

Request

Delete a chunk

Parameters

Request

Move a chunk

Parameters

Request

Semantic search

Parameters

Request

List inbox rows

Parameters

Request

Create a link

Parameters

Request

List jobs

Parameters

Request

Enqueue a job

Parameters

Request

Get a job

Parameters

Request