Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.writeback.dev/llms.txt

Use this file to discover all available pages before exploring further.

Base URL: https://api.writeback.dev

​
Authentication

Two key types:
KeyPrefixUse
Ingest keywk_Submit reports (write-only)
API keywk_sk_Read reports and projects (Bearer token)
Get both from your dashboard.

​
Submit a report

POST /v1/reports
Submit a feedback report from an agent. Authenticated with an ingest key — no Authorization header needed. Request body: 
{
  "ingest_key": "wk_your_ingest_key",
  "outcome": "failure",
  "details": "What the agent tried and what happened",
  "tool_name": "optional — the specific tool or endpoint",
  "source": "optional — name of your skill, MCP server, or API"
}
FieldTypeRequiredDescription
ingest_keystringYesYour project’s ingest key
outcomestringYessuccess, failure, confusing, gave_up, or request
detailsstringYesNatural language description of what happened
tool_namestringNoThe specific tool or endpoint used
sourcestringNoName of your skill, MCP server, or API
Response: 
{ "ok": true, "id": "5fedcdff6fde60fe35214876abada9a1" }
Example: 
curl -X POST https://api.writeback.dev/v1/reports \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_key": "wk_your_ingest_key",
    "outcome": "confusing",
    "tool_name": "search_index",
    "details": "Parameter name in docs says query but the actual field name is q. Got a 400 until I guessed correctly."
  }'

​
List projects

GET /v1/projects
Authorization: Bearer wk_sk_your_api_key
Returns all projects for your account. Response: 
[
  {
    "id": "bf9166a67ee9834f16850d3794b10e93",
    "name": "my-project",
    "created_at": "2026-02-20T11:06:14Z"
  }
]

​
Get reports

GET /v1/dashboard/:projectId/reports
Authorization: Bearer wk_sk_your_api_key
Returns reports and stats for a project. Query parameters:
ParamDescription
outcomeFilter by outcome value
tool_nameFilter by tool name
sourceFilter by source
fromStart date (ISO 8601)
toEnd date (ISO 8601)
pagePage number (default: 1)
limitResults per page (default: 50, max: 100)
Response: 
{
  "project": { "id": "...", "name": "my-project" },
  "stats": {
    "total": 41,
    "success": 25,
    "failure": 5,
    "confusing": 8,
    "gave_up": 0,
    "request": 3
  },
  "reports": [
    {
      "id": "...",
      "outcome": "failure",
      "tool_name": "search_index",
      "source": "my-mcp-server",
      "details": "...",
      "created_at": "2026-02-20T13:02:23Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 41 }
}