Agent docs

Report v1 contract

Fields, limits, ingestion responses, idempotency, and a working curl request.

Submit a report

Create a show token in Settings → Agents, save the payload below as report.json, then send it to the public Report v1 endpoint.

curl --fail-with-body \
  -X POST "https://www.audioreality.ai/v1/reports" \
  -H "Authorization: Bearer $AUDIOREALITY_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @report.json

A bare report is accepted as a batch of one. Send up to 100 reports as { "reports": [...] }. Accepted batches return HTTP 202; a malformed body returns 422.

Report object

{
  "source": "ci",
  "agent": "release-checks",
  "status": "warn",
  "title": "Checkout test passed on retry",
  "summary": "One browser test timed out, then passed on the automatic retry.",
  "links": [{
    "label": "Workflow run",
    "url": "https://github.com/example/repo/actions/runs/123"
  }],
  "run_id": "123",
  "occurred_at": "2026-09-16T07:42:00Z",
  "metrics": { "retries": 1 },
  "tags": ["checkout"]
}

sourceRequired slug: 1–64 lowercase letters, digits, dots, underscores, or hyphens.

agentOptional agent, skill, or job name; 64 characters.

statusok, warn, fail, or needs_decision.

titleRequired; 140 characters.

summaryRequired; 2,000 characters. This is the only body text hosts may quote.

detailsOptional follow-up grounding; 20,000 characters. Never spoken verbatim or included in a roll call.

linksUp to five HTTP(S) links with 60-character labels.

run_idOptional 128-character idempotency and supersession key.

occurred_atOptional RFC 3339 timestamp; defaults to the ingestion time.

metricsUp to ten number, string, or boolean values.

tagsUp to ten tags, each no longer than 32 characters.

Response and queue

The response counts accepted, superseded,duplicates, and per-index rejected reports. It also returns the show name, next delivery, and queue counts for decisions, failures, warnings, green reports, and mail.

Reports with the same source and run_id are duplicates when their status is unchanged. A different status supersedes the earlier report. Use that transition to resolveneeds_decision work.

Limits and errors

Requests are limited to 256 KiB and 600 reports per show per UTC day.
Blocked sources return 403; an invalid or rotated token returns 401.
Rate limits return 429 with error.retry_after.
All errors use { "error": { "code", "message", "issues"?, "retry_after"? } }.