diff --git a/docs/infra/agent_api.md b/docs/infra/agent_api.md
new file mode 100644
index 0000000..30664dc
--- /dev/null
+++ b/docs/infra/agent_api.md
@@ -0,0 +1,198 @@
+# Agent API — Claude sitt strukturerte grensesnitt mot maskinrommet
+
+## Bakgrunn
+
+I dag snakker Claude med systemet via `claude -p` med hele konteksten
+bakt inn som en tekststreng. Det fungerer for enkle chat-svar, men
+skalerer ikke:
+
+- Prompten blir enorm når spec + historikk + graf-kontekst skal med
+- Claude kan ikke *hente mer info* underveis — alt må være i prompten
+- Claude kan ikke *gjøre handlinger* (oppdatere spec, søke, sjekke status)
+- Ingen struktur — alt er fritekst, ingen validering
+
+## Konsept
+
+Et sett med maskinrommet-endepunkter designet for agenten — ikke for
+brukere. Autentisert med agent-token (samme som i `agent_identities`).
+Gir Claude strukturert tilgang til grafen, spesifikasjoner og handlinger.
+
+## Endepunkter
+
+### Lesing (kontekst)
+
+#### `GET /agent/context`
+Hent alt Claude trenger for å svare i en samtale.
+
+```
+GET /agent/context?communication_id=<uuid>
+```
+
+Returnerer:
+```json
+{
+  "communication": { "id": "...", "title": "..." },
+  "participants": [{ "id": "...", "title": "...", "node_kind": "..." }],
+  "messages": [{ "id": "...", "content": "...", "sender": "...", "timestamp": "..." }],
+  "spec": { "id": "...", "content": "...", "feature_key": "..." } | null,
+  "related_nodes": [{ "id": "...", "title": "...", "edge_type": "..." }]
+}
+```
+
+Fordel over dagens løsning: én request, strukturert, med spec og
+relaterte noder inkludert. Maskinrommet bestemmer hva som er relevant.
+
+#### `GET /agent/node`
+Hent en spesifikk node med edges.
+
+```
+GET /agent/node?id=<uuid>&depth=1
+```
+
+Returnerer noden med edges i angitt dybde. Nyttig når Claude trenger
+mer kontekst enn det som var i `context`-svaret.
+
+#### `GET /agent/search`
+Søk i grafen.
+
+```
+GET /agent/search?q=<tekst>&node_kind=content&limit=10
+```
+
+PG fulltekstsøk over nodes.content + nodes.title. Filtrering på
+node_kind, visibility, samling. Returnerer noder med relevans-score.
+
+#### `GET /agent/feature_status`
+Sjekk implementeringsstatus for en feature.
+
+```
+GET /agent/feature_status?key=lydstudio
+```
+
+Returnerer:
+```json
+{
+  "feature_key": "lydstudio",
+  "spec_node_id": "...",
+  "tasks": [
+    { "id": "17.1", "description": "...", "status": "done" },
+    { "id": "17.2", "description": "...", "status": "todo" }
+  ],
+  "recent_commits": ["..."],
+  "feedback_summary": "3 brukere har gitt feedback, 1 ubesvart"
+}
+```
+
+Henter fra tasks.md (parser markdown), git log, og feedback-chat.
+
+#### `GET /agent/tasks`
+Hent gjeldende oppgavestatus.
+
+```
+GET /agent/tasks?phase=14&status=todo
+```
+
+Parser tasks.md og returnerer strukturert. Filtrer på fase og status.
+
+### Skriving (handlinger)
+
+#### `POST /agent/update_spec`
+Oppdater en spec-node.
+
+```json
+{
+  "node_id": "...",
+  "content": "oppdatert markdown...",
+  "reason": "Integrert feedback fra bruker X om Y"
+}
+```
+
+Oppdaterer noden i STDB + PG. Logger endringen i `ai_usage_log`
+med `job_type: 'spec_update'`. Oppretter `revision`-node med
+forrige versjon for historikk.
+
+#### `POST /agent/respond`
+Send et svar i en samtale (erstatter dagens direkte STDB-skriving).
+
+```json
+{
+  "communication_id": "...",
+  "content": "svarteksten",
+  "metadata": { "confidence": 0.9, "sources": ["node_id_1"] }
+}
+```
+
+Maskinrommet håndterer node-opprettelse, edges, og STDB-synk.
+Metadata kan inkludere kildereferanser som frontend kan vise.
+
+#### `POST /agent/suggest_edges`
+Foreslå nye edges basert på innholdsanalyse.
+
+```json
+{
+  "source_id": "...",
+  "suggestions": [
+    { "target_id": "...", "edge_type": "mentions", "confidence": 0.85 },
+    { "target_id": "...", "edge_type": "related_to", "confidence": 0.7 }
+  ]
+}
+```
+
+Lagres som forslag (`metadata.suggested: true`) — bruker eller admin
+godkjenner. Over en viss confidence-terskel kan de auto-godkjennes.
+
+## Autentisering
+
+Agent-endepunktene bruker agent-token fra `agent_identities`-tabellen.
+Samme token som brukes for STDB-tilkobling. Header:
+
+```
+Authorization: Bearer <agent_token>
+```
+
+Maskinrommet validerer at tokenet tilhører en aktiv agent
+(`is_active = true`). Agentens `node_id` brukes som `created_by`
+for alle handlinger.
+
+## Integrasjon med `claude -p`
+
+Dagens `agent_respond`-jobb kaller `claude -p` med en tekstprompt.
+Med Agent API endres flyten:
+
+### Før (nåværende)
+```
+melding → agent_respond-jobb → bygg prompt (SQL) → claude -p → parse svar → skriv STDB+PG
+```
+
+### Etter (med Agent API)
+```
+melding → agent_respond-jobb → GET /agent/context → claude -p med tool-definisjon → claude bruker tools → POST /agent/respond
+```
+
+Claude får tool-definisjoner i prompten og kan kalle Agent API via
+tool-use i JSON-output. Maskinrommet parser tool-calls og utfører dem.
+
+Alternativt: Claude Code har allerede tool-bruk via Bash. Agent API
+kan eksponeres som `curl`-kommandoer som Claude kaller direkte.
+
+## Prioritering
+
+### Fase 1 (umiddelbar verdi)
+- `GET /agent/context` — erstatter SQL-i-prompten, gir spec-kontekst
+- `POST /agent/respond` — strukturert svar med metadata
+
+### Fase 2 (bedre feedback-løkke)
+- `GET /agent/feature_status` — Claude kan gi informerte statussvar
+- `POST /agent/update_spec` — Claude kan integrere feedback direkte
+- `GET /agent/search` — Claude kan finne relevant kontekst selv
+
+### Fase 3 (proaktiv agent)
+- `POST /agent/suggest_edges` — automatisk grafbygging
+- `GET /agent/tasks` — Claude kan rapportere på fremdrift
+- Periodiske jobber: digest, spec-synk, feedback-oppsummering
+
+## Bygger på
+- Agent-infrastruktur (`docs/infra/claude_agent.md`)
+- Feature feedback (`docs/features/feature_feedback.md`)
+- Jobbkø (`docs/infra/jobbkø.md`)
+- AI Gateway (`docs/infra/ai_gateway.md`)