Record what an AI agent said it needed and could not find (agent feedback)

POST /api/v1/agent-feedback · operationId recordAgentFeedback

For developers: your server sends this request with a server key; it is not a button in the dashboard.

Stored only while the workspace has agent feedback on; otherwise answered {stored: false, reason: "off"} and nothing is kept. Never feeds verdicts, rules, confidence or billing. Sent by adapters/mcp (feedback: true).

#Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

#Request body

Content-Type: application/json (required)

• eventId (string, required) · pattern ^[A-Za-z0-9_-]{8,128}$
• text (string, required) · maxLength 2000: What the agent wrote. Redacted here (e-mail addresses, credential-like strings, long digit runs and URL query strings) and cut to 500 characters before it is stored.
• tool (string, optional) · maxLength 64
• at (integer, optional)
• client (object, optional)
• client.name (string, required) · maxLength 64
• client.version (string, optional) · maxLength 32
• accountId (string, optional) · maxLength 512
• userId (string, optional) · maxLength 512
• session (object, optional)
• session.key (string, required) · pattern ^[a-f0-9]{32,64}$
• session.source ("customer" | "transport" | "derived", required)

{
  "eventId": "feedback_00000001",
  "text": "Needed a tool to export last month’s invoices as CSV; found only list_invoices.",
  "tool": "list_invoices",
  "at": 1762300800000,
  "client": {
    "name": "Claude Code",
    "version": "2.1.0"
  },
  "accountId": "acct_456",
  "userId": "usr_123"
}

#Responses

• 200: Success · body object
• 400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
• 401: unauthorized (missing or invalid server key, missing Bearer scheme) · body Error
• 403: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body Error
• 404: not_found: unknown path, or an ID in the path that is not on this Site · body Error
• 409: conflict: the request contradicts what is already recorded; message says what · body Error
• 413: payload_too_large: the request body exceeds 131072 bytes · body Error
• 429: rate_limited: wait for Retry-After · body Error · headers Retry-After
• 500: internal_error: fail the protected action; do not retry automatically · body Error
• 503: service_unavailable: temporarily unavailable; only verify retries · body Error

#Success body fields

• stored (boolean, required)
• replayed (boolean, optional)
• id (string, optional)
• reason ("off", optional)

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

#Example

curl -sS -X POST 'https://app.trytelltale.dev/api/v1/agent-feedback' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"eventId":"feedback_00000001","text":"Needed a tool to export last month’s invoices as CSV; found only list_invoices.","tool":"list_invoices","at":1762300800000,"client":{"name":"Claude Code","version":"2.1.0"},"accountId":"acct_456","userId":"usr_123"}'

const response = await fetch("https://app.trytelltale.dev/api/v1/agent-feedback", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "eventId": "feedback_00000001",
    "text": "Needed a tool to export last month’s invoices as CSV; found only list_invoices.",
    "tool": "list_invoices",
    "at": 1762300800000,
    "client": {
      "name": "Claude Code",
      "version": "2.1.0"
    },
    "accountId": "acct_456",
    "userId": "usr_123"
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.