# marginalia public API

**Canonical:** https://apis.io/apis/polycode-co-uk/marginalia-public-api/  
**Provider:** Polycode — https://apis.io/providers/polycode-co-uk/  
**Base URL:** https://marginalia.polycode.co.uk/api  
**Documentation:** https://marginalia.polycode.co.uk/developers

marginalia public API is one of 2 APIs that [Polycode](https://apis.io/providers/polycode-co-uk/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Chat, Memory, Agents, Knowledge Graph, and Research. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.

Public read + chat REST API for marginalia, the memory-graph chat agent operated by Polycode Limited. 50 operations under /api: async one-turn chat with task polling, an OpenAI-shaped mechanical completion shim, memory-graph listing, session search and history, insights, projects, usage and budget, and key-authed private-graph provisioning. OpenAPI 3.0.3 served at https://marginalia.polycode.co.uk/api/openapi.json.

## Operations (50)

| Method | Path | Summary |
|---|---|---|
| GET | `/api/graphs/default` | Resolve the current default graph id. |
| GET | `/api/graphs` | List memory graphs (past + current). `?all=1` bypasses the margin cap. |
| POST | `/api/graphs` | (Tier-1) Create a private graph (archived-from-birth, owner-only, cap 16). Returns the one-time API key. |
| GET | `/api/status` | Deployment status: caps, default graph, bedrock_enabled, mode, version. |
| GET | `/api/usage` | Bedrock usage drill-down for a scope. |
| GET | `/api/usage/all` | Every LLM call or web search in a calendar month. |
| GET | `/api/budget` | Today + month-to-date spend vs caps, plus Tavily credits. |
| GET | `/api/diverts` | The graph's standing mechanical auto-diverts (Reflex) + today's avoided-turn ROI. |
| GET | `/api/graph/{graphId}/activity` | Recent synth turns for a graph. |
| GET | `/api/graph/{graphId}/session/{sessionUuid}/history` | Turn history for a session. |
| GET | `/api/graph/{graphId}/session/{sessionUuid}/meta` | Session meta (introduction, searchability). |
| GET | `/api/graph/{graphId}/insights` | Latest hourly insights for a graph. |
| GET | `/api/graph/{graphId}/daily-summary` | Latest daily typed-edge prose summary (markdown) for a graph. |
| GET | `/api/graph/{graphId}/entities` | Extracted OWL types view: domain classes, object properties, and individuals. |
| POST | `/api/graph/{graphId}/insights/refresh` | Regenerate a graph's insights now; returns the fresh snapshot. |
| GET | `/api/graph/{graphId}/turn/{turnId}` | A single turn by id. |
| GET | `/api/sessions` | Full-text search across session introductions. |
| GET | `/api/sessions/log` | Combined visitor + socials message log: per-session channel, shortened ids, created time, message count. |
| GET | `/api/visitor/{visitorId}` | Pseudonymous visitor meta (label, creation time). |
| GET | `/api/projects` | List a graph's projects (default: the current graph). |
| GET | `/api/projects/{projectId}` | Project detail: file map, log, suggestions. |
| GET | `/api/projects/{projectId}/file` | Read a project file by relpath. |
| POST | `/api/project/{projectId}/op` | (Admin for the shared graph; owner for a private graph) Project lifecycle op: { action: "reopen"\|"conclude"\|"archive"\|"delete", note? }. |
| GET | `/api/openapi.json` | This OpenAPI document. |
| POST | `/api/chat` | Async one-turn chat: returns 202 + a task id; poll /api/chat/result. sessionUuid is optional — minted and returned when omitted (reuse it to keep conversatio... |
| POST | `/api/v1/chat/completions` | OpenAI-shaped MECHANICAL completion shim: { messages } → grammar Formulate → SPARQL Solve → template Render. Token-free (usage all 0); the `marginalia` block... |
| GET | `/api/chat/result` | Poll an async chat task: working \| completed (with reply) \| failed. |
| POST | `/api/keys` | (Tier-1, logged-in) Provision a private graph + mint an API key (shown once). Send { action: "delete", hash } to delete one of your own keys. |
| GET | `/api/keys` | (Tier-1) List the caller's private graphs + their API-key metadata (hash, issued_at, last-4 suffix; never plaintext). |
| GET | `/api/keys/whoami` | (X-API-Key) Which graph does this key resolve to? Key-authed self-discovery: { graph_id, issued_by, suffix }. Never echoes the key. |
| POST | `/api/test/seed` | Prime behaviour-test fixtures into the sandbox graph (sandbox-only). |
| POST | `/api/flag` | Flag a memory node for operator review. |
| POST | `/api/visitor/{visitorId}/label` | Set a visitor's screened, unverified label. |
| POST | `/api/graph/{graphId}/session/{sessionUuid}/introduction` | Set a visitor's session introduction. |
| POST | `/api/graph/{graphId}/export` | Export a graph (stub). |
| POST | `/api/graphs/{graphId}/repo` | (Owner of a private graph; admin for a public graph) Bind the graph to a source repo: { repo_owner, repo_slug, repo_url?, default_branch?, intent_path?, lice... |
| GET | `/api/graph/{graphId}/summary` | (Owner/admin/X-API-Key) Build the compact screened showcase seed (summary.json shape) from the live graph — top-N degree-ranked summaries + themes + provenance. |
| POST | `/api/graphs/default/clear` | (Tier-1) Clear the caller's per-user default graph (revert to the shared graph). |
| POST | `/api/me/default-graph` | (Tier-1+) Set the caller's default graph: { graphId } — a private graph you own, or the shared default. Keyed A2A/chat requests that name no graph land here. |
| POST | `/api/graphs/{graphId}/delete` | (Owner) Delete a private graph + its tree, keys, and default pointer. |
| POST | `/api/graphs/{graphId}/label` | (Owner of a private graph; admin for any graph) Rename a graph (single-token, screened). |
| POST | `/api/graphs/{graphId}/default` | (Owner) Set this private graph as the caller's login default. |
| GET | `/api/graphs/{graphId}/prompt-note` | (Owner of a private graph; admin for a public graph) Read the graph's free-text prompt note. |
| POST | `/api/graphs/{graphId}/prompt-note` | (Owner of a private graph; admin for a public graph) Set { note } — free text (max 2000 chars, guardrail-screened) injected into the graph's system prompt. E... |
| POST | `/api/admin/work-item` | (Admin) Create or comment on a GitLab work item: { action: "create", title, description, labels? } or { action: "comment", iid, body }. REST mirror of the wo... |
| POST | `/api/admin/turn` | (Admin) Trigger an autonomous turn now: { graphId? } — async-invokes the turn lambda with force (bypasses the cadence gate); graphId targets one graph, else ... |
| POST | `/api/admin/delivery` | (Admin) GitLab delivery-loop action: { action: assign \| mr_review \| mr_comment \| mr_comment_assign \| mr_merge \| mr_close \| pipeline_status \| issue_close, iid... |
| POST | `/api/hooks/gitlab/{graphId}` | (Connector secret) GitLab webhook receiver for a bound supervisor graph — X-Gitlab-Token constant-time-validated against the binding; kept events are shaped ... |
| POST | `/api/hooks/github/{graphId}` | (GitHub HMAC) GitHub webhook receiver for a bound graph — X-Hub-Signature-256 constant-time-verified against the org webhook secret in SSM (/marginalia/{env}... |
| POST | `/api/hooks/push` | (X-API-Key) Generic collector: batched { messages: [{ label, body, source_refs?, actor? }] } shaped and queued into the key's bound graph (plain-git history,... |

## Machine-readable artifacts (7)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/polycode-co-uk/refs/heads/main/openapi/polycode-co-uk-marginalia-openapi.json
- **OpenAPI** — https://marginalia.polycode.co.uk/api/openapi.json
- **Documentation** — https://marginalia.polycode.co.uk/developers
- **APIReference** — https://marginalia.polycode.co.uk/api/openapi.json
- **Overlay** — https://raw.githubusercontent.com/api-evangelist/polycode-co-uk/refs/heads/main/overlays/polycode-co-uk-marginalia-overlay.yaml
- **Sandbox** — https://raw.githubusercontent.com/api-evangelist/polycode-co-uk/refs/heads/main/sandbox/polycode-co-uk-sandbox.yml
- **APIsJSON** — https://raw.githubusercontent.com/api-evangelist/polycode-co-uk/refs/heads/main/apis.yml

## Other Polycode APIs (1)

- [marginalia A2A Agent](https://apis.io/apis/polycode-co-uk/marginalia-a2a-agent/)

## Tags

Chat, Memory, Agents, Knowledge Graph, Research

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/polycode-co-uk/marginalia-public-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/polycode-co-uk/.