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

# Express API

> Add a POST /feedback endpoint to your Express app.

## Installation

```bash theme={null}
npm install writeback-sdk
```

## Usage

```typescript theme={null}
import express from 'express';
import { feedbackRouter } from 'writeback-sdk/express';

const app = express();

app.use(express.json());

// Mount the feedback router
app.use(feedbackRouter({ ingestKey: 'wk_your_ingest_key' }));

app.listen(3000);
```

This adds a `POST /feedback` endpoint to your app.

## What it does

`feedbackRouter` returns an Express router that handles `POST /feedback`. When an agent calls it, the report is submitted to your writeback dashboard.

The endpoint accepts a JSON body:

| Field       | Type   | Required | Description                                                     |
| ----------- | ------ | -------- | --------------------------------------------------------------- |
| `outcome`   | string | Yes      | One of: `success`, `failure`, `confusing`, `gave_up`, `request` |
| `details`   | string | Yes      | What the agent tried and what happened                          |
| `tool_name` | string | No       | The specific endpoint or operation being reported on            |
| `source`    | string | No       | Name of your API or service                                     |

**Example request:**

```bash theme={null}
curl -X POST https://your-api.com/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "confusing",
    "tool_name": "POST /v1/analyze",
    "details": "The docs say the content param accepts markdown but do not specify a max length. Sent 12k tokens and got a 400 with no error message."
  }'
```

**Response:**

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

## Options

```typescript theme={null}
feedbackRouter({
  ingestKey: 'wk_your_ingest_key', // required
  path: '/feedback',                // optional — default is /feedback
  source: 'my-api',                 // optional — identifies your service in reports
})
```

## Document it for agents

For agents to know your feedback endpoint exists, document it in your OpenAPI spec or API description:

```yaml theme={null}
paths:
  /feedback:
    post:
      summary: Report feedback about this API
      description: >
        Use this endpoint to report what happened after using any part of this API.
        Submit after errors, confusion, or successful completions.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [outcome, details]
              properties:
                outcome:
                  type: string
                  enum: [success, failure, confusing, gave_up, request]
                details:
                  type: string
                tool_name:
                  type: string
```

## Getting an ingest key

Sign up at [dashboard.writeback.dev](https://dashboard.writeback.dev) and create a project. Your ingest key is write-only — safe to include in environment variables.

```typescript theme={null}
feedbackRouter({
  ingestKey: process.env.WRITEBACK_INGEST_KEY!,
})
```