Base URL

http://localhost:3001/api

Authentication

API endpoints require authentication via session cookie or API key header:

# Using API key
curl -H "Authorization: Bearer sk_..." http://localhost:3001/api/observations

# Using session cookie (after login)
curl --cookie "authjs.session-token=..." http://localhost:3001/api/observations

Observations

List Observations

GET /api/observations

Query Parameters:

Parameter	Type	Description
project	string	Filter by project
type	string	Filter by type
limit	number	Max results (default: 50)
offset	number	Pagination offset
sort	string	created_at or updated_at

Response:

{
  "observations": [
    {
      "id": 42,
      "title": "Fixed N+1 in UserList",
      "type": "bug",
      "content": "What: Added batch loading...",
      "topic_key": "bugfix/n1-userlist",
      "project_id": "my-app",
      "scope": "project",
      "pinned": false,
      "read_only": false,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 342,
  "limit": 50,
  "offset": 0
}

Create Observation

POST /api/observations

Body:

{
  "title": "Chose PostgreSQL over MongoDB",
  "type": "decision",
  "content": "What: Using PostgreSQL\nWhy: ACID compliance needed",
  "topic_key": "architecture/database",
  "project_id": "my-app",
  "scope": "project"
}

Get Observation

GET /api/observations/:id

Update Observation

PATCH /api/observations/:id

Delete Observation

DELETE /api/observations/:id

Search

GET /api/search?q=database+choice&type=decision&limit=10

Uses FTS5 full-text search across all observations.

Sessions

Start Session

POST /api/sessions

{
  "project_id": "my-app"
}

End Session

POST /api/sessions/:id/end

Session Summary

POST /api/sessions/:id/summary

Stats

GET /api/stats

Returns observation counts by type, session count, and project list.

Error Responses

All errors follow this format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Observation 999 not found"
  }
}

Code	HTTP Status	Description
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request body
UNAUTHORIZED	401	Missing or invalid auth
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error