Docs / Getting started

Quickstart

Five minutes from a blank page to a shareable diagram with a request and a response on it.

This walkthrough builds a small diagram of an app asking an auth server for a token and then calling an API. You need nothing but a browser.

#1. Open the editor

Go to volley.sh/edit. The first time, it opens with an example so you can see what a finished diagram looks like. To start from nothing, choose New diagram in the sidebar. It opens a starter diagram with one arrow:

title: Untitled

Client -> Server: Request

The source is on the left and the drawing on the right. The drawing updates as you type.

#2. Name your lanes with a message

A lane is one participant, such as a browser, a service or a database. You never declare lanes. They appear the first time a message names them. Replace the starter text with this:

title: Fetch invoices

App -> Auth Server: POST /oauth2/token
Auth Server --> App: 200 OK
App -> API: GET /invoices
API --> App: 200 OK

Four arrows, three lanes. -> is a request and --> is a reply. Volley pairs each dashed reply with the request it answers, so selecting one highlights the other.

#3. Attach what each call sends

Now the part that makes a Volley diagram useful. Put an in: block on the line right after a message for what it sends, and an out: block for what comes back:

volley

title: Fetch invoices

App -> Auth Server: POST /oauth2/token
in: Token request
  grant_type: client_credentials
  client_id: billing-worker
  client_secret: <redacted>

Auth Server --> App: 200 OK
out: Token
```json
{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 900 }
```

App -> API: GET /invoices
in: Headers
  Authorization: Bearer eyJhbGciOi...

API --> App: 200 OK
out: Invoices
```json
[{ "id": "inv_123", "total": 4200, "currency": "USD" }]
```

Notice:

• key: value lines need no fence. Volley reads them as fields.
• A JSON body goes in a fenced block tagged json.
• <redacted> marks a secret. Volley shows it as redacted instead of as a value.

#4. Read it back

Click any arrow in the drawing. The inspector opens beside the diagram with the route, the request or response it pairs with, and each payload as a table of fields with a Raw tab for the original body. To see every payload at once, turn on Show payloads in the bar under the diagram.

Press J and K to step through the messages while one is selected, and Esc to close the inspector.

#5. Fix a mistake

Type a line of plain prose, such as then the app retries, between two messages and watch the problems bar under the editor. It says Unrecognized line and names the line and column. Click the problem to jump to it. Volley still draws everything it can understand, so one mistake never blanks the diagram. Delete the line, or turn it into a note with note: then the app retries.

#6. Share it

Open the Share menu in the toolbar and choose Copy share link. The link carries the whole diagram inside the URL, so anyone who opens it sees exactly what you see, and nothing is stored on a server. Your draft also stays in this browser, so it is there when you come back.

If you sign in with GitHub or Google, the diagram is saved to your account automatically and gets a short link such as volley.sh/d/abc123 that always shows the latest version. See Accounts and saving.

#Next steps

• Learn the rest of the language in the Syntax reference.
• Add branches for success and error cases with if and else in Notes, branches and dividers.
• Skip the typing: import a HAR file from your browser's network tab.
• Put the diagram in a README with an embed.