Docs / Agents and API

Agents overview

Volley is built to be written by agents as much as by people. Pick the interface that fits where your agent runs.

Volley's syntax is short, regular and forgiving, and every error comes with a line and a column. That makes it easy for an AI agent to write a diagram, check it, read the errors and fix them without a person in the loop. Agents can reach Volley in five ways.

#Choose an interface

Agents can also read context without any key: an unlisted collection or diagram is available as Markdown at its address plus .md. See Collections.

#API keys

The MCP server and the HTTP API need an API key.

1. Sign in, then choose Connect an agent in the sidebar under Agents, or API keys in the Account menu.
2. Give the key a name that says where it will live, such as "Claude Code on my laptop", and click Create a key.
3. Copy the key straight away. Volley shows it only once and stores only a hash of it.

The dialog also shows the MCP server's address and a ready-to-paste command for Claude Code.

Keys start with volley_. Send one in any of these headers:

Authorization: Bearer volley_...
X-Api-Key: volley_...

The Authorization header also accepts the key on its own, without Bearer, for tools that pass the value through unchanged.

The keys table shows each key's name, the start of the key, when it was created and when it was last used. Revoke stops a key working at once.

#Usage and limits

Calls to the HTTP API and to the MCP server's tools share one monthly allowance per account, whichever key made them.

• The count resets on the first of each month, UTC.
• Every metered HTTP response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time) headers.
• Requests that fail before they run, such as a bad key or malformed JSON, are not counted.
• Over the limit, the API answers 429 and MCP tools return an error result that says so.
• The API keys dialog shows how many calls you have used this month.

Listing tools on the MCP server, and the .md context addresses, do not count.

#Tips for agents writing Volley

• Run check after every change and fix errors by line number before rendering or saving.
• Use describe to read a diagram back as Markdown, including every payload. It is often a better input for reasoning than the raw source.
• Put real field names in payloads, and <redacted> in place of secrets.
• Start HTTP messages with the method and path, such as POST /oauth2/token, so the diagram can be checked against recordings later.
• Fence payload bodies whose keys could read as statements, such as title: or order:.