Skip to Content
v1.39.1 · shipped More settings on the script tag · Script tag typos no longer slip through Read the changelog →
QuickstartHTTP API (curl, no SDK)

HTTP API: one curl, no SDK

Use the API when an SDK does not fit: a server, a cron job, a script, a no-code tool, or a language Mushi Mushi has no SDK for. One POST files a report. Mushi Mushi diagnoses it like a report from the widget.

Get your project ID and key

Run npx mushi-mushi in your app’s folder. It signs you in through your browser and writes both values to .env.local (*_MUSHI_PROJECT_ID and *_MUSHI_API_KEY). No app folder? Open Manage apps in the console , pick your project and click Generate API key.

This key can only send reports. It cannot read them, so it is safe in a page or a public script.

Send a report

curl -sS https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api/v1/reports -H "Content-Type: application/json" -H "X-Mushi-Api-Key: $MUSHI_API_KEY" -d '{"projectId":"'"$MUSHI_PROJECT_ID"'","category":"bug","description":"The Save button on the settings page does nothing.","reporterToken":"curl-test-1","createdAt":"2026-11-18T09:00:00Z","environment":{"url":"https://example.com/settings","userAgent":"curl","platform":"server","language":"en","viewport":{"width":0,"height":0},"referrer":"","timestamp":"2026-11-18T09:00:00Z","timezone":"UTC"}}'
You’ll see: {"ok":true,"data":{"reportId":"…","status":"submitted"}}, then the report in the console  with a title, how serious it is and the likely cause, usually within a minute.

Check it

curl -sS https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api/v1/reports/REPORT_ID/status -H "X-Mushi-Api-Key: $MUSHI_API_KEY"
You’ll see: the status (new, then classified), the category, the severity and a one-line summary.

The fields

Every field below is required. The rest of the body is optional.

FieldWhat to send
projectIdYour project ID. It must match the key’s project.
categorybug, slow, visual, confusing, other, feedback, question or feature
descriptionWhat the user saw, in their words. Up to 5,000 characters.
reporterTokenA random ID for the person reporting, with no name or email in it. Reports with the same token group together.
createdAtThe time, in ISO 8601 with a time zone, for example 2026-11-18T09:00:00Z.
environmenturl, userAgent, platform, language, viewport (width, height), referrer, timestamp, timezone. Send "" or 0 when you have no value.

Optional fields that make the diagnosis better: severity (low to critical), consoleLogs, networkLogs, screenshotDataUrl (a data: URL, about 1.5 MB at most), metadata, and environment.route.

A missing field returns 400 with the field named, for example {"ok":false,"error":{"code":"INGEST_ERROR","message":"environment.timezone: Required"}}.

Keys and scopes

Each key has scopes. Use the smallest one that does the job.

ScopeWhat it can doWhere it can live
report:writeSend reports, spans and metrics; read its own report’s statusIn your app or a public script
mcp:readRead reports, diagnoses and lessons (/v1/sync/*, MCP)On your computer or a server only
mcp:writeEverything mcp:read can, plus replying to reporters and starting fixesOn your computer or a server only

Never put an mcp:read or mcp:write key in a web page. Mushi Mushi refuses such a key once it has been seen in a browser (KEY_EXPOSED_IN_BROWSER).

Rate limits

RouteLimit, per project
POST /v1/reports and /v1/reports/batch120 reports a minute (you can change it per project); a batch counts each report
POST /v1/ingest/spans500 calls a minute
POST /v1/ingest/metrics60 calls a minute

Over the limit you get 429 RATE_LIMITED with a Retry-After header in seconds. When the plan’s monthly reports run out you get 402 QUOTA_EXCEEDED, also with Retry-After. Wait that long, then retry.

To make a retry safe, add an id to the body (a UUID you make once per report). Sending the same id again returns the report already stored instead of filing a second one. The same reporter, text and category within 60 seconds is also merged into the first report.

More than one report

POST /v1/reports/batch takes {"reports":[…]}. It keeps the first 10 and drops the rest, and checks each report on its own, so one bad report does not fail the others.

OpenAPI spec

The full machine-readable spec (OpenAPI 3.1) is at /functions/v1/api/openapi.json. Point a code generator or an agent at it. It covers ingest, the /v1/sync/* read routes, fix dispatch and the A2A task routes.

Want your editor to read reports instead of calling the API by hand? Use the MCP server.

Last updated on