Docs / Getting started
How Volley works
The handful of ideas that the rest of the docs build on.
On this page
Diagrams are text
A Volley diagram is a short text file. Volley parses it and draws a sequence diagram: lanes as columns, messages as arrows from top to bottom in the order they happen. Because the source is text, it diffs cleanly in pull requests, an agent can write it, and you can keep it next to the code it describes. The file extension is .volley.
The vocabulary
| Term | Meaning |
|---|---|
| Lane | One participant: a browser, a service, a database, a person. Created the first time it is named. |
| Message | One arrow from one lane to another, such as App -> API: GET /me. Every message has a number, starting at 1. |
| Payload | The data a message carries. An input (in:) is what the sender sends; an output (out:) is what comes back. |
| Reply | A dashed arrow. Volley pairs it with the request it answers. |
| Section | An if or group block that wraps steps. An if can have several else branches. |
| Note, divider, delay | Explanations and pacing that are not calls. |
| Source | The text of the diagram. |
Payloads are the point
Most sequence diagrams show who calls whom and stop there, which leaves the reader guessing what each call sends. In Volley, every arrow can carry the real request and response: parameters, JSON bodies, headers and status codes. The drawing stays readable because payloads are tucked behind the arrow until someone asks for them. See Requests and responses.
Where your diagram lives
| You are | Your diagram is kept | Others see it through |
|---|---|---|
| Signed out | In this browser only, as a draft that saves as you type | A share link that carries the whole diagram in the URL, a downloaded file, or an image |
| Signed in | In your account, saved automatically, at a short link like /d/abc123 | The short link, a README embed, or any of the signed-out options |
Share links put the diagram after the # in the URL. Browsers do not send that part to any server, so a share link works without Volley storing anything. See Data and privacy.
From text, or from traffic
You can write a diagram by hand, or start from what really happened:
- Import a HAR file recorded in your browser's network tab.
- Catch real deliveries in a webhook inbox.
- Send a customer a recording link.
And once you have a diagram, update it from a recording to find the steps where the real API no longer matches.
People and agents
Everything in Volley works for both. People get the editor, the inspector, presentations and embeds. Agents get the same diagrams through the MCP server, the HTTP API, the command line, the agent skill and in-page tools. Errors always come with a line and a column so an agent can fix its own mistakes.