Skip to main content

Record a Decision

POST /decisions
Authorization: Bearer ek_...

{
  "workspace_id": "ws_abc123",
  "title": "Use JWT for authentication",
  "rationale": "Stateless, works with edge deployment",
  "type": "architecture",
  "files": ["src/auth/login.ts", "src/auth/middleware.ts"]
}
Response
{
  "id": "dec_abc123",
  "title": "Use JWT for authentication",
  "rationale": "Stateless, works with edge deployment",
  "type": "architecture",
  "made_by": "usr_xyz",
  "workspace_id": "ws_abc123",
  "files": ["src/auth/login.ts"],
  "created_at": "2026-04-13T10:00:00Z"
}
Decisions are also typically recorded via the decide MCP tool.

Search Decisions

Semantic vector search over all decisions in the workspace.
POST /decisions/search
Authorization: Bearer ek_...

{
  "workspace_id": "ws_abc123",
  "query": "authentication and session management",
  "limit": 5
}
Response
{
  "results": [
    {
      "id": "dec_abc",
      "title": "Use JWT for authentication",
      "rationale": "Stateless, works with edge deployment",
      "type": "architecture",
      "similarity": 0.92,
      "made_by": "Developer A",
      "created_at": "2026-04-13T10:00:00Z"
    }
  ]
}
Search is also available via the search MCP tool.

List Decisions

GET /workspaces/:id/decisions
Authorization: Bearer ek_...
Query params:
  • type — filter by decision type
  • made_by — filter by user ID
  • limit — max results (default: 50)
  • before — cursor for pagination

Decision Types

TypeDescription
architectureHigh-level system design
approachFeature implementation approach
implementationLow-level implementation detail
rejectionExplicitly rejected alternative
tradeoffDocumented tradeoff
conventionAdopted team pattern
bugfixRoot cause and fix