# RentSeek Feedback Intake

Structured product-feedback reports from the website, developer API, and MCP agents.

Human triage owns disposition. Submissions do not open GitHub issues or pull requests,
and they do not trigger autonomous fixes.

## Endpoint

```http
POST https://rentseek.ing/api/feedback
Content-Type: application/json
```

Authentication is optional. Send `X-API-KEY` for the authenticated rate-limit tier.
Anonymous submissions are allowed and rate-limited more tightly. Optional
`Idempotency-Key` header: a duplicate submit returns `200` with the same `fb_` id.

Anonymous intake is fail-closed. If the rate limiter is unavailable, the request
returns `503` with code `FEEDBACK_UNAVAILABLE` and nothing is persisted.

Reports are stored in Postgres. IP addresses are stored only as HMAC hashes.

## Schema `feedback/v1`

Required fields:

- `schema_version`: `feedback/v1`
- `category`: `bug`, `data_quality`, `docs`, `api`, `mcp`, `other`
- `message`: 10–2000 characters
- `surface`: `website`, `developer_api`, `mcp`

Optional fields:

- `url`: http(s) URL or site-relative path
- `route`: site-relative path such as `/developers`
- `tool`: MCP tool name when reporting from an agent
- `request_id`, `trace_id`: opaque correlators
- `context`: `ticker`, `fiscal_year`, and/or `executive_id` only

Arbitrary keys are rejected. Raw bodies over 8192 bytes are rejected
based on bytes actually read, not only `Content-Length`. Secret-bearing or PII-bearing
payloads are rejected without persist. Logs record only `event`, `code`, `surface`,
`principalKind`, and `requestId`.

## Success

```json
{
  "schema_version": "feedback/v1",
  "id": "fb_…",
  "status": "accepted"
}
```

The `id` is opaque and non-guessable. Keep it if you need to follow up.

## Errors

Website submissions (`surface=website`) use the nested app envelope
`{ "error": { "code": string, "message": string } }`.

Developer API and MCP HTTP clients use the public provider envelope
`{ "error": string, "message": string }`.

Anonymous limiter failures use `503` and code `FEEDBACK_UNAVAILABLE`.

## Website and MCP

- Website form: https://rentseek.ing/feedback
- MCP tool: `submit_feedback` on https://rentseek.ing/mcp — same validator, same feedback
  rate limiter, `surface` is set to `mcp`