Docs / Agents and API

HTTP API

Five endpoints for scripts, CI jobs and services that need to check or render diagrams.

The HTTP API checks, describes, parses, renders and verifies diagrams. It is stateless: you send a diagram, you get a result. To work with saved diagrams and collections, use the MCP server.

#Basics

• Base address: https://volley.sh/api/v1/
• Method: POST for every endpoint.
• Authentication: an API key in Authorization: Bearer volley_... or X-Api-Key: volley_....
• Body: the diagram as raw text, or JSON {"source": "..."} with Content-Type: application/json. Diagrams can be up to 256 KB.
• Allowance: each successful call counts once against your monthly allowance. See Usage and limits.

curl -s https://volley.sh/api/v1/check \
  -H "Authorization: Bearer $VOLLEY_KEY" \
  --data-binary @checkout.volley

#check

POST /api/v1/check validates a diagram.

{
  "ok": false,
  "summary": "3 lanes, 4 messages, 2 payloads",
  "diagnostics": [
    { "severity": "error", "line": 7, "column": 1, "message": "Unrecognized line: \"foo bar\"" }
  ]
}

ok is false only when there is at least one error. Warnings leave it true.

#describe

POST /api/v1/describe returns the diagram as Markdown (text/markdown): the title, the lanes, every message in order with its number, its replies and its payloads in code blocks, notes and sections, and a list of problems if there are any. It is a good format for an agent to read, or to paste into a document.

#json

POST /api/v1/json returns the parsed diagram as JSON: title, autonumber, actors (the lanes, in display order), elements (messages, notes, dividers, delays and sections, nested as in the source) and diagnostics. Each message includes its number, lanes, arrow style, input and output payloads with their parsed fields, and the numbers of the request it answers or the replies that answer it.

#svg

POST /api/v1/svg returns a standalone SVG image (image/svg+xml).

curl -s "https://volley.sh/api/v1/svg?theme=dark&payloads=1" \
  -H "Authorization: Bearer $VOLLEY_KEY" \
  --data-binary @checkout.volley > checkout.svg

Images made with a Free account carry a small "Made with Volley" badge; Pro images do not.

#verify

POST /api/v1/verify runs a drift check of a diagram against a recording. Send JSON with the diagram and the HAR file:

{ "source": "title: Checkout\n...", "har": { "log": { "entries": [] } } }

har can be the parsed HAR object or its text. The diagram can be up to 256 KB and the recording up to 8 MB. The easiest way to build the body is with jq:

jq -n --rawfile source checkout.volley --slurpfile har checkout.har \
  '{source: $source, har: $har[0]}' |
curl -s https://volley.sh/api/v1/verify \
  -H "Authorization: Bearer $VOLLEY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

The response is the full report. This one is shortened to one step:

{
  "passed": false,
  "summary": { "checked": 4, "matched": 2, "drifted": 2, "missing": 0, "skipped": 0, "undocumented": 1 },
  "messages": [
    {
      "index": 2,
      "status": "drift",
      "request": { "id": 0, "method": "POST", "host": "auth.example.com", "path": "/oauth2/token", "status": 200 },
      "outOfOrder": false,
      "expectedStatus": 200,
      "fields": [
        { "side": "output", "kind": "type", "path": "expires_in", "expected": "number", "observed": "string" },
        { "side": "output", "kind": "undocumented", "path": "scope" }
      ],
      "summary": "1 field changed type, 1 undocumented field."
    }
  ],
  "undocumented": [{ "id": 2, "method": "POST", "host": "api.example.com", "path": "/invoices/inv_9001/reminders", "status": 202 }]
}

• status is match, drift, missing or skipped.
• Each field difference has a kind of missing, undocumented or type.
• passed is true when nothing drifted or is missing and at least one step matched.

See Update from a recording for a complete GitHub Actions job.

#Errors

Errors are JSON with a code and a message you can show to a person:

{ "error": "rate_limited", "message": "You have used all 200 API calls for this month. Upgrade to Volley Pro for more.", "upgrade": true }

upgrade: true means a Pro plan would allow the request.

The API does not send CORS headers, so call it from a server or script, not from a web page.