---
title: "Submit feedback (humans via the site widget, agents via direct POST)"
method: POST
path: "/v1/feedback"
tags: ["intake"]
---

# Submit feedback (humans via the site widget, agents via direct POST)

`POST /v1/feedback`

## Request

- Base URL: `https://cotal.ai`
- URL: `https://cotal.ai/v1/feedback`
- Auth: one of:
  - none
  - HTTP bearer

Open intake. An optional `Authorization: Bearer ctk_…` team key is recorded as a hash for attribution and marks the submission as trusted when recognized. Supports `Idempotency-Key` and `X-Sandbox`.

## Headers

- `Idempotency-Key` string
- `X-Sandbox` 'true' | 'false'

## Request body

- FeedbackInput
  - `origin` 'human' | 'agent'
  - `type` 'bug' | 'idea' | 'friction' | 'praise' | 'other'
  - `summary` string, required: Required, non-empty.
  - `email` string, email, required: Required — feedback must have a traceable origin.
  - `severity` 'low' | 'medium' | 'high'
  - `name` string
  - `details` string
  - `area` string
  - `repro` string
  - `expected` string
  - `actual` string
  - `source` string: Where it came from, e.g. a page path, agent name, or CLI.

## Response `200`

Stored (or replayed for a known Idempotency-Key). Returns the record id.

- SubmitOk
  - `ok` true, required
  - `id` string, uuid, nullable: Record id; null when nothing was stored (duplicate, honeypot, or sandbox).
  - `replayed` boolean: True when a known Idempotency-Key returned the original record.
  - `sandbox` boolean: Present and true on X-Sandbox dry runs.

## Other responses

- `400`: Malformed body or validation error (`code`: bad_request | validation_error).
- `413`: Body over the size cap (`code`: payload_too_large).
- `429`: Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.
- `502`: Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.
- `default`: Any other failure. The body is always the Error object, with a stable `code` and a `hint`.

---

[API](https://skmtc.dev/cotal/apis/cotal-ai-public-api.md) · [All operations](https://skmtc.dev/cotal/apis/cotal-ai-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cotal/apis/cotal-ai-public-api/revisions/34ab992f2172?raw)