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.

​
Installation

npm install writeback-sdk

​
Usage

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:
FieldTypeRequiredDescription
outcomestringYesOne of: success, failure, confusing, gave_up, request
detailsstringYesWhat the agent tried and what happened
tool_namestringNoThe specific endpoint or operation being reported on
sourcestringNoName of your API or service
Example request: 
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: 
{ "ok": true, "id": "abc123" }

​
Options

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: 
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 and create a project. Your ingest key is write-only — safe to include in environment variables. 
feedbackRouter({
  ingestKey: process.env.WRITEBACK_INGEST_KEY!,
})