Back to app

Developer docs

Agent reports

File structured output from monitors, standups, research agents, and digest workers into a private show. Registry identity always wins over identity claims inside report content.

Register an agent

Open Step 5: Agents in your show, choose a display name, route, and kind, then store the bearer key shown once. A key belongs to one agent in one show and can be revoked immediately.

Report schema

Every payload uses audioreality.report.v1. The stable JSON Schema is served at /api/agent-reports/schema.

agentDisplay hints only: name and monitor, standup, research, digest, or custom kind.
runISO start/finish and ok, warning, or failure status.
headlinePlain text, 140 characters maximum.
summaryPlain text editorial summary, 1,200 characters maximum.
itemsUp to 50 bounded items with status, severity 0–3, detail, optional HTTPS URL, and numeric metrics.
stale_afterISO timestamp. Stale reports are never selected for an episode.
prioritynormal or high; an editorial hint, never an interrupt.
{
  "schema": "audioreality.report.v1",
  "agent": { "name": "Repo monitor", "kind": "monitor" },
  "run": {
    "started_at": "2026-08-22T10:00:00Z",
    "finished_at": "2026-08-22T10:01:00Z",
    "status": "warning"
  },
  "headline": "Two checks need attention",
  "summary": "The build passed, but latency moved outside its usual range.",
  "items": [{
    "title": "API latency",
    "status": "warning",
    "severity": 2,
    "detail": "P95 increased during the latest run.",
    "metrics": { "p95_ms": 840 }
  }],
  "stale_after": "2026-08-23T10:01:00Z",
  "priority": "high"
}

HTTPS

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

Valid reports return 202. Invalid schemas return422 with field paths. Duplicate reports are idempotent.

GitHub Actions

- name: File AudioReality report
  if: always()
  env:
    AUDIOREALITY_AGENT_KEY: ${{ secrets.AUDIOREALITY_AGENT_KEY }}
  run: |
    curl --fail-with-body \
      -X POST "https://www.audioreality.ai/api/agent-reports" \
      -H "Authorization: Bearer $AUDIOREALITY_AGENT_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @report.json

MCP

The stateless Streamable HTTP endpoint exposesfile_report, validate_report, and metadata-only get_queue_status. It never exposes mail, reports, scripts, or transcripts for reading.

{
  "mcpServers": {
    "audioreality": {
      "type": "http",
      "url": "https://www.audioreality.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:audioreality-agent-key}"
      }
    }
  }
}

Email

Send to the dedicated plus-address shown for the registered agent. Attach report.json as application/json, or put the same payload in a fenced json block. Attachment takes precedence. The From address is never trusted for attribution.

Limits and security

  • 256 KB per report and 24 reports per agent per UTC day by default.
  • Plain text only; HTML and attachments on the HTTPS path are rejected.
  • Report URLs are cited but never fetched in this release.
  • Content is untrusted evidence and cannot change host or system behavior.
  • Failures and warnings lead; all-green reports collapse into one roll call.

Validator