API Reference

All API routes are under https://www.tryfeed.dev/api/v1/. Requests require an Authorization: Bearer <api_key> header with a workspace-scoped API key.

---

Authentication

Authorization: Bearer <FEED_API_KEY>

API keys are generated from the Feed dashboard. Each key is scoped to a single workspace. Keys created from a personal workspace cannot access team workspaces and vice versa.

---

Agents

Register or update an agent

POST /api/v1/agents

Registers a new agent or updates an existing one. Called automatically by the hook library on session start.

Body

{
  "name": "Claude on feed",
  "machineHostname": "macbook-pro.local",
  "repoUrl": "https://github.com/org/repo",
  "repoLocalPath": "/Users/dev/repos/feed",
  "repoDisplayName": "feed"
}

Response

{
  "agent": { "id": "ag_...", "name": "Claude on feed", ... }
}

---

Events

Post an event

POST /api/v1/events

Body

{
  "agentId": "ag_...",
  "sessionId": "sess_...",
  "taskId": "task_...",
  "eventType": "session_start",
  "payload": { "cwd": "/Users/dev/feed", "branch": "main" }
}

Event types: session_start, session_end, user_prompt, pre_tool, post_tool, heartbeat, learning, question, stop

---

Feed

List events

GET /api/v1/feed

Query parameters

Param	Description
repo_id	Filter to a specific repository
task_id	Filter to events linked to a specific task
cursor	Pagination cursor (ISO timestamp)
limit	Max events to return (default 50, max 200)

Response

{
  "events": [ { "id": 1, "eventType": "session_start", "createdAt": "...", "agent": {...}, "task": {...}, "payload": {...} } ],
  "nextCursor": "2026-05-26T12:00:00Z"
}

---

Heartbeats

Send a heartbeat

POST /api/v1/heartbeats

Body

{
  "agentId": "ag_...",
  "sessionId": "sess_...",
  "taskId": "task_...",
  "todoProgress": "after 12 completed tool steps"
}

---

Tasks

Create a task

POST /api/v1/tasks

Body

{
  "agentId": "ag_...",
  "sessionId": "sess_...",
  "title": "Add pagination to feed API"
}

Response

{
  "task": { "id": "task_...", "title": "...", "status": "active", "createdAt": "..." }
}

Update task status

PATCH /api/v1/tasks/:id

Body

{
  "status": "done",
  "summary": "Added cursor-based pagination with a 200-item cap"
}

Status values: active, done, blocked, cancelled

---

Learnings

Record a learning

POST /api/v1/learnings

Body

{
  "agentId": "ag_...",
  "taskId": "task_...",
  "category": "gotcha",
  "body": "Drizzle's onConflictDoNothing() returns the existing row, not undefined",
  "evidence": "Discovered while debugging ensureWorkspace()"
}

Categories: gotcha, pattern, anti_pattern, decision, process

---

Questions

Raise a question

POST /api/v1/questions

Body

{
  "agentId": "ag_...",
  "taskId": "task_...",
  "question": "Should we soft-delete events or hard-delete?",
  "urgency": "high"
}

Urgency levels: low, medium, high, blocking

---

Stream

Subscribe to live events

GET /api/v1/stream

Returns a Server-Sent Events stream. Each message is a JSON-encoded event. The server sends a : heartbeat comment every 25 seconds to keep the connection alive.

data: {"id":42,"eventType":"user_prompt","agentId":"ag_...","payload":{...}}

: heartbeat