# Volley > Volley (https://volley.sh) draws API sequence diagrams from plain text. Each arrow can carry the request and response it sends (JSON, form bodies, headers, query strings), so a reader sees who calls whom and exactly what was sent. The editor is free and needs no account. ## Give a person a diagram as a link If you are an assistant writing a sequence diagram for someone, write it in Volley syntax and give them a link that opens it in the editor: https://volley.sh/edit#text= Percent-encode the whole source the way encodeURIComponent does, including newlines (%0A), spaces (%20), "+" (%2B), "#" (%23) and "&" (%26). The text after the # is never sent to a server. The person can edit the diagram, click any arrow to see its payloads, export SVG or PNG, and share it. A minimal working link: https://volley.sh/edit#text=title%3A%20Ping%0AApp%20-%3E%20API%3A%20GET%20%2Fhealth%0AAPI%20--%3E%20App%3A%20200%20OK Also show the source in a code block, so the person can read it without opening the link. Keep links under about 8,000 characters; for longer diagrams, give the source and tell the person to paste it into https://volley.sh/edit. ## Syntax - `title: text` names the diagram. `order: A, B, C` fixes the lane order. `autonumber` numbers messages. - A message is `From -> To: label`. A lane appears the first time it is named. Arrows: `->` request, `-->` dashed reply, `=>` bold, `->>` open, `-x` lost, `<->` both ways. `A -> A` is a self message. - A dashed reply answers the latest open request between the same two lanes, so label replies with the status, such as `API --> App: 200 OK`. - Payloads go on the lines right after a message: `in: title` for what is sent, `out: title` for what comes back. The body is one fenced block (```json, ```form, ```http, ```headers, ```params, ```text) or indented `key: value` lines. Write `` for secrets. - `note: text` explains the message above it. `note A, C: text` spans lanes A to C. - `if: label`, `else: label` and `end` show alternatives. `group: label` ... `end` draws a box. Sections nest one level. - Dividers: `_: text` thin, `=: text` bold. Delays: `...: text`. Comments start with `//`. - Inline Markdown works in labels and notes. Icons: `{fas-lock}`, `{fab-stripe}`. ## Example ``` title: Exchange a code for a token App -> Auth Server: POST /oauth/token in: Token request ```form grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=web-app ``` Auth Server --> App: 200 OK out: Token response ```json { "access_token": "", "token_type": "Bearer", "expires_in": 3600 } ``` App -> API: GET /invoices?status=open in: Headers Authorization: Bearer API --> App: 200 OK out: Invoices ```json [{ "id": "inv_1", "total": 4200, "currency": "usd" }] ``` ``` ## Tools for agents - [Remote MCP server](https://volley.sh/docs/mcp): `https://volley.sh/mcp` checks, renders, saves and reads diagrams. Needs a free API key. - [HTTP API](https://volley.sh/docs/http-api): `check`, `describe`, `json`, `svg` and `verify` endpoints. - [Agents overview](https://volley.sh/docs/agents): choosing between the MCP server, HTTP API, CLI, agent skill and in-page tools. - [Syntax guide](https://volley.sh/docs/syntax): every construct with examples. ## Templates - [Stripe Checkout sequence diagram with webhook payloads](https://volley.sh/templates/stripe-checkout): A Stripe Checkout sequence diagram with the real requests: creating the Checkout Session, the redirects, and the checkout.session.completed webhook that fulfils the order. Open it and edit it. - [Stripe PaymentIntent sequence diagram with 3D Secure](https://volley.sh/templates/stripe-payment-intents): A Stripe PaymentIntents sequence diagram: create the intent, confirm with the Payment Element, the requires_action 3D Secure step, the return_url and the payment_intent.succeeded webhook. - [GitHub OAuth sequence diagram: Sign in with GitHub](https://volley.sh/templates/github-oauth): A sequence diagram of Sign in with GitHub using an OAuth app: the authorize redirect, the code exchange, the bad_verification_code error and the /user call, with every parameter on its arrow. - [JWT refresh token sequence diagram with rotation](https://volley.sh/templates/jwt-refresh-token): A JWT refresh token sequence diagram: login, a short-lived access token, an httpOnly refresh cookie, the 401 on expiry, refresh with rotation, the retry and reuse detection. - [SAML SSO sequence diagram with the real requests](https://volley.sh/templates/saml-sso): A SAML 2.0 SP-initiated single sign-on sequence diagram with the AuthnRequest, the auto-posting form, the SAMLResponse at the ACS URL and the assertion checks, step by step. - [Shopify webhook sequence diagram: orders/create](https://volley.sh/templates/shopify-order-webhook): A sequence diagram of Shopify's orders/create webhook: the delivery headers and order JSON, HMAC verification, a fast 200, and background work through the GraphQL Admin API. - [GitHub webhook sequence diagram: pull_request and checks](https://volley.sh/templates/github-webhook): A GitHub webhook sequence diagram: the pull_request delivery headers, X-Hub-Signature-256 verification, a fast 202, and a check run posted back with an installation token. - [Twilio SMS webhook sequence diagram with TwiML](https://volley.sh/templates/twilio-sms-webhook): A sequence diagram of Twilio's incoming SMS webhook: the form-encoded request, X-Twilio-Signature validation, and the TwiML reply that Twilio sends back as a text message. - [Slack slash command sequence diagram](https://volley.sh/templates/slack-slash-command): A Slack slash command sequence diagram: the form-encoded command, signing secret verification, the 3-second acknowledgement and a delayed message through response_url. - [MCP sequence diagram: Model Context Protocol tool call](https://volley.sh/templates/mcp-tool-call): A Model Context Protocol sequence diagram over Streamable HTTP: initialize, Mcp-Session-Id, notifications/initialized, tools/list, the model choosing a tool, and tools/call. - [LLM tool calling sequence diagram: the tool use loop](https://volley.sh/templates/llm-tool-use): An LLM tool calling sequence diagram with the Claude Messages API: tools with a JSON schema, a tool_use response, your app running the tool, the tool_result and the final answer. - [S3 presigned URL upload sequence diagram](https://volley.sh/templates/s3-presigned-upload): An S3 presigned URL upload sequence diagram: the browser asks for a signed PUT URL, uploads straight to the bucket, gets an ETag, confirms with your server, plus the S3 event. ## Optional - [Pricing](https://volley.sh/pricing): free editor; Pro for saved diagrams, history, private diagrams and higher limits. - [AI sequence diagrams](https://volley.sh/ai-sequence-diagram-generator): prompts and setup for chat assistants and coding agents.