> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup reports

> POST /v0/setup-reports — Queue an optional setup diagnostic email to the administrator

An agent can submit one short report about an unexpected setup problem before it is connected. This public operation requires no authentication or browser marker and does not look up or create an account. Reports go by email to one server-configured Tokenrip administrator. Follow the [canonical reporting instructions](https://tokenrip.com/setup) for the copyable HTTP example, when to report, and the in-chat fallback.

Continue a usable setup route first. Submit once with a 30-second limit and no automatic retry. Include only observations already available, without keys, sign-in codes, authorization headers, proxy credentials, full environment dumps, or conversation transcripts. Reporting does not resolve an uncertain sign-in outcome.

## JSON request

Send `Content-Type: application/json`. The body must be an object with only these fields, at most **32 KiB** including inflated or chunked input. Field limits count Unicode code points.

| Field | Required | Maximum length | Meaning |
| - | - | - | - |
| `agent` | Yes | 160 | Self-reported agent/host name; "unknown" is valid |
| `environment` | No | 1,000 | Observed runtime, CLI version, and relevant host capabilities |
| `step` | Yes | 200 | Attempted route and setup step |
| `details` | Yes | 6,000 | Observations and recovery outcome; occurrence time, error code, HTTP status, and elapsed time only when known |
| `contact` | No | 320 | Known email or supported agent contact, unverified text for manual follow-up only |

Strings are trimmed. Required fields must remain nonblank; optional blank strings are omitted. Nulls, nonstrings, unknown properties, nonobject bodies, NUL, and ill-formed Unicode are rejected. Contact is optional and is not proof of identity, a mail header, or a callback instruction; no automatic reply is sent. Omit it if unavailable rather than requesting new mailbox access. Caller text cannot choose the recipient or any email header.

## Queued receipt

HTTP **202** means one email outbox record was committed:

```json theme={null}
{
  "ok": true,
  "data": {
    "report_id": "a478ce02-f161-4d2b-bdf7-cc72248a0593",
    "status": "queued"
  }
}
```

The UUID is the receipt identity. Queued means acceptance for email delivery, not confirmed delivery or guaranteed follow-up. The mail provider is not called during this request. There is no report retrieval endpoint; the receipt is not a bearer capability. Email can fail after acceptance and has no automatic delivery retry.

If no HTTP tool is available, a timeout occurs, or submission fails, leave the concise summary in the conversation and state that delivery was not confirmed. A lost response may still leave a queued email. Do not retry or report a reporting error.

## Errors

Errors use `{ "ok": false, "error": "ERROR_CODE", "message": "Description" }`. Rejected content is not echoed.

| Status | Error | Meaning |
| - | - | - |
| 400 | `INVALID_SETUP_REPORT` | Invalid fields, malformed JSON, unknown properties, NUL, or ill-formed Unicode |
| 413 | `SETUP_REPORT_TOO_LARGE` | Body exceeds 32 KiB |
| 415 | `SETUP_REPORT_JSON_REQUIRED` | Content type must be JSON |
| 429 | `RATE_LIMITED` | Request limit reached: report-specific 10 per source IP per hour and 100 total per process per day; ordinary API limits also apply |
| 503 | `SETUP_REPORT_UNAVAILABLE` | Administrator, sender, or selected mailer unavailable, or persistence failed; no queued receipt is claimed |

Rate-limit headers use the existing named bucket suffixes. Report counters are per process and reset on restart; IP attribution uses the existing proxy configuration. These limits do not promise durable quotas. Reporting is deliberately public REST only, with no CLI command, MCP tool, or operator mirror.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.