Setup reports
curl --request POST \
--url https://api.example.com/v0/setup-reportsimport requests
url = "https://api.example.com/v0/setup-reports"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/setup-reports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/setup-reports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/setup-reports"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/setup-reports")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/setup-reports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyOverview
Setup reports
POST /v0/setup-reports — Queue an optional setup diagnostic email to the administrator
POST
/
v0
/
setup-reports
Setup reports
curl --request POST \
--url https://api.example.com/v0/setup-reportsimport requests
url = "https://api.example.com/v0/setup-reports"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/setup-reports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/setup-reports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/setup-reports"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/setup-reports")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/setup-reports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyAn 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 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.
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.
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.
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.
JSON request
SendContent-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 |
Queued receipt
HTTP 202 means one email outbox record was committed:{
"ok": true,
"data": {
"report_id": "a478ce02-f161-4d2b-bdf7-cc72248a0593",
"status": "queued"
}
}
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 |