Cotal
DocsAPI Reference

Submit tester feedback

POST
/v1/feedback

Authenticate the tester key, reserve one rate-limit admission, validate and persist the record, then attempt mesh publication. Tester identity comes from the provisioned key record, not the request body. Raw diagnostics are not echoed in the response.

Authorization

FeedbackKey
headerAuthorizationBearer <token>

Provisioned tester key. The bearer scheme is case-insensitive; the key is trimmed.

Request Body

application/json
  1. body

Strings are trimmed before length checks. Empty or null optional strings are omitted. Unknown properties are discarded. client and diagnostics accept arbitrary JSON.

origin*string
Value in"human""agent"
type*string
Value in"bug""idea""friction""praise""other"
summary*string
Length1 <= length <= 300
severity?string
Value in"low""medium""high"
client?unknown
diagnostics?unknown
details?|
Lengthlength <= 10000
area?|
Lengthlength <= 120
repro?|
Lengthlength <= 10000
expected?|
Lengthlength <= 5000
actual?|
Lengthlength <= 5000
source?|
Lengthlength <= 40

Response Body

Stored feedback. published reports whether mesh publication was confirmed.

application/json
  1. response
ok*unknown
id*string
Formatuuid
published*boolean
Example Request
curl -X POST 'http://127.0.0.1:8787/v1/feedback' \  -H 'Content-Type: application/json' \  -d '{  "origin": "human",  "type": "friction",  "summary": "The setup command did not explain the missing broker.",  "severity": "low"}'
Example Response
{  "ok": true,  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "published": true}

See the HTTP interface overview for authentication and access requirements.

Complete HTTP contract

Endpoint

POST /v1/feedback

Authenticate the tester key, reserve one rate-limit admission, validate and persist the record, then attempt mesh publication. Tester identity comes from the provisioned key record, not the request body. Raw diagnostics are not echoed in the response.

Parameters

No operation parameters.

Request body

The request uses the schema below.

Required: yes.

Content type: application/json.

{
  "$ref": "#/components/schemas/Feedback"
}

Example:

{
  "origin": "human",
  "type": "friction",
  "summary": "The setup command did not explain the missing broker.",
  "severity": "low"
}

Responses

HTTP 202

Stored feedback. published reports whether mesh publication was confirmed.

Content type: application/json.

{
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "published": {
      "type": "boolean"
    }
  },
  "required": [
    "ok",
    "id",
    "published"
  ],
  "additionalProperties": false
}

HTTP 400

Malformed JSON or invalid fields.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

Missing or invalid tester key.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 413

Feedback body exceeds the configured byte limit.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Tester exceeded the configured fixed-minute admission limit.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

Unexpected intake failure.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

Authentication and access: HTTP interface of the reference feedback intake service. The default listener is 127.0.0.1:8787 and the operator can configure host and port. Health is unauthenticated. Feedback requires a provisioned tester key. The service persists an accepted record before publishing it to the feedback channel. A 202 with published false still means the record was stored. This implementation reference does not establish a hosted public feedback product.

The body limit defaults to 65536 bytes and is configurable with --max-bytes. The rate limit defaults to 30 authenticated admissions per tester per fixed minute, configurable with --rate-limit. Failed body validation still consumes an admission. Query strings are accepted because dispatch uses the URL pathname. Unknown paths and methods return JSON 404. The handler does not enforce Content-Type or Origin and sends no CORS promise.

OpenAPI specification contains the referenced response schemas. Complete Markdown reference.

Health GET

Read feedback intake health