> ## 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.

# API Reference

> Direct HTTP API for submitting and reading reports.

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

## Authentication

Two key types:

| Key        | Prefix   | Use                                      |
| ---------- | -------- | ---------------------------------------- |
| Ingest key | `wk_`    | Submit reports (write-only)              |
| API key    | `wk_sk_` | Read reports and projects (Bearer token) |

Get both from your [dashboard](https://dashboard.writeback.dev).

***

## Submit a report

```http theme={null}
POST /v1/reports
```

Submit a feedback report from an agent. Authenticated with an ingest key — no Authorization header needed.

**Request body:**

```json theme={null}
{
  "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"
}
```

| Field        | Type   | Required | Description                                                |
| ------------ | ------ | -------- | ---------------------------------------------------------- |
| `ingest_key` | string | Yes      | Your project's ingest key                                  |
| `outcome`    | string | Yes      | `success`, `failure`, `confusing`, `gave_up`, or `request` |
| `details`    | string | Yes      | Natural language description of what happened              |
| `tool_name`  | string | No       | The specific tool or endpoint used                         |
| `source`     | string | No       | Name of your skill, MCP server, or API                     |

**Response:**

```json theme={null}
{ "ok": true, "id": "5fedcdff6fde60fe35214876abada9a1" }
```

**Example:**

```bash theme={null}
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

```http theme={null}
GET /v1/projects
Authorization: Bearer wk_sk_your_api_key
```

Returns all projects for your account.

**Response:**

```json theme={null}
[
  {
    "id": "bf9166a67ee9834f16850d3794b10e93",
    "name": "my-project",
    "created_at": "2026-02-20T11:06:14Z"
  }
]
```

***

## Get reports

```http theme={null}
GET /v1/dashboard/:projectId/reports
Authorization: Bearer wk_sk_your_api_key
```

Returns reports and stats for a project.

**Query parameters:**

| Param       | Description                              |
| ----------- | ---------------------------------------- |
| `outcome`   | Filter by outcome value                  |
| `tool_name` | Filter by tool name                      |
| `source`    | Filter by source                         |
| `from`      | Start date (ISO 8601)                    |
| `to`        | End date (ISO 8601)                      |
| `page`      | Page number (default: 1)                 |
| `limit`     | Results per page (default: 50, max: 100) |

**Response:**

```json theme={null}
{
  "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 }
}
```