POST /v1/deliberate

Submit a decision question for multi-model deliberation. Returns a structured Decision Memo.

Endpoint

POST https://api.decisionmemos.com/v1/deliberate

Headers

Header	Required	Description
Authorization	Yes	Bearer token: `Bearer dm_...`
Content-Type	Yes	`application/json`
Accept	No	`text/event-stream` for SSE streaming

Request body

{
  "question": "Should we migrate to a monorepo?",
  "userEmail": "you@example.com",
  "criteria": [
    { "name": "Developer experience", "description": "How does this affect DX?" },
    { "name": "CI/CD complexity", "description": "Build pipeline impact" }
  ],
  "stream": false,
  "transparent": false,
  "context": "We have 12 repos across 3 teams...",
  "byok": {
    "openai": "sk-...",
    "anthropic": "sk-ant-..."
  }
}

Fields

Field	Type	Required	Description
question	string	Yes	The decision to deliberate
userEmail	string	Yes	Account email so the memo is saved to your account and counted toward your quota.
criteria	Criterion[]	No	Evaluation dimensions
stream	boolean	No	Enable SSE streaming (default: false)
transparent	boolean	No	Show real model names (default: false)
context	string	No	Additional context for the panel
byok	object	No	Your own provider API keys. 20% off per key supplied, up to 80% with all 4.

Response

Returns a DecisionMemo JSON object. See the Decision Memo schema for the full type.

Error responses

// 401 - Invalid or missing API key
{ "error": "unauthorized", "message": "Invalid API key" }

// 401 - Missing user identity (userEmail required)
{ "error": "authentication_required", "message": "userEmail is required. Include your account email so the memo is saved to your account." }

// 422 - Validation error
{ "error": "validation_error", "message": "question is required" }

// 429 - Rate limited
{ "error": "rate_limited", "message": "Too many requests", "retryAfter": 30 }

// 500 - Server error
{ "error": "internal_error", "message": "Deliberation failed" }

Note

If one provider fails during deliberation, the remaining advisors still produce their perspectives. The memo will include a note about the missing advisor.