Documenting Multi-Step Workflows So Agents Can Sequence Your API

An API reference describes pieces. Each endpoint page tells an agent what one call does: the method, the path, the parameters, the response shape. Almost no real task is one call. "Send an email" through a transactional email API is a sequence — create an API key, verify a sending domain, register a sender address, send the message, handle the delivery webhook — and the reference documents each of those steps as if it stood alone. The ordered path from nothing to outcome is a separate piece of writing, and most APIs never write it.

When the sequence is unwritten, an AI agent does what a model does with missing information: it invents one. It calls the send endpoint before the domain is verified, hits a 422, and retries the same call in a loop, because nothing in the docs said the 422 meant "go back two steps." Across the APIs Discry scans, this is one of the most consistent patterns in the scan evidence: docs that describe every endpoint accurately and still leave an agent unable to complete a task, because the assembly instructions exist only in the heads of the team that built the API.

This article covers what a workflow doc is, shows a worked example you can copy, and lays out where workflow documentation has to live for agents to find it.

What the corpus shows

Discry's scan evidence records how each API's public docs handle multi-step tasks, and the corpus splits cleanly into APIs that wrote the sequence down and APIs that left it implied.

On the written-down side, the patterns are concrete. Mercury's docs include end-to-end recipes such as send-an-ACH: list accounts, list recipients, then POST the transaction with an idempotency key — a real chain with realistic values, so an agent follows the path instead of guessing it. Twilio's docs pair task-oriented endpoint descriptions with multi-step quickstarts that chain operations together with error handling, and every page offers a native view-as-Markdown link. Resend's framework guides walk install → template → send → verify for each stack they support. In each case the workflow is a first-class documentation object with a URL, fetchable over plain HTTP.

On the implied side, the failure modes repeat across the corpus. One exchange API documents its endpoints in isolation with no end-to-end guides, so an agent must infer the create-key → fund-account → place-order → poll-status chain on its own. A sports-data API leaves the agent to assemble a five-step chain — sports, competitions, fixtures, fixture detail, live socket — because no guide walks through connect, retrieve, and handle as a sequence. A market-data API describes what each call returns but never how to chain calls or recover from a failed request. These are accurate reference docs. They still fail the agent, because the reference genre was never designed to carry sequence.

The distinction matters commercially for the reason the agent-readiness pillar lays out: agents choose the APIs they can find and understand, and understanding a multi-step API means understanding the order.

What a workflow doc is

A workflow doc is the assembly instructions for one outcome. It has five parts, and each part answers a question an agent otherwise has to guess.

Goal. The outcome in one line, stated as a state of the world: "a delivered email with a verifiable delivery event." Agents plan backward from goals; a goal stated as an endpoint ("how to use POST /emails") gives them nothing to plan toward.

Preconditions. What must already exist before step one: an account, DNS access, a sandbox project, a billing method. Unstated preconditions are the silent killers of agentic workflows — the agent executes five perfect calls against an account that was never eligible to succeed.

Ordered calls. The numbered sequence of requests, each with its method and path. Order is the entire point. If step 3 fails without step 2, the doc says so at step 3, at the moment the agent needs it.

State passed between calls. What each step produces and what the next step consumes: the domain.id from step 2 becomes a parameter in step 3; the token from step 1 authenticates everything after it. This is the part reference docs structurally cannot carry, because each page only knows about its own request and response.

Failure exits. Where the workflow can dead-end, how the agent recognizes each exit, and what recovery looks like — retry, wait, go back a step, or stop. A workflow doc that only documents the happy path documents half the workflow.

A worked example

Here is a complete workflow doc for a realistic transactional email API — the "zero to sent email" path. It is short enough to fit on one docs page and complete enough that an agent can execute it without inventing anything.

## Workflow: send your first email (zero to delivered)

**Goal:** a delivered email, confirmed by a delivery event.
**Preconditions:** an account; DNS edit access for the sending domain.

### Steps

1. **Create an API key.** `POST /api-keys` → returns `key.token`,
   shown once. Every later call sends
   `Authorization: Bearer <key.token>`.

2. **Register the sending domain.** `POST /domains` with
   `{"name": "mail.example.com"}` → returns `domain.id` plus the
   SPF and DKIM records to add to DNS.
   **Wait state:** poll `GET /domains/{domain.id}` until
   `status: "verified"`. Verification follows DNS propagation —
   minutes to hours. Unverified after 72h → exit F1.

3. **Create a sender.** `POST /senders` with a from-address on the
   verified domain → returns `sender.id`.
   Returns `422 domain_not_verified` if step 2 is incomplete →
   exit F2. Do not retry-loop; block on step 2.

4. **Send.** `POST /emails` with `sender.id`, recipient, subject,
   body, and an `Idempotency-Key` header so a retried request
   cannot double-send → returns `email.id`, `status: "queued"`.

5. **Confirm delivery.** Register a webhook endpoint
   (`POST /webhooks`, event `email.delivered`) or poll
   `GET /emails/{email.id}`. Terminal states: `delivered`,
   or `bounced` → exit F3.

### Failure exits

- **F1 — domain never verifies.** DNS records are missing or wrong.
  Re-fetch them from `GET /domains/{domain.id}` and compare against
  the zone before retrying.
- **F2 — sent before verification.** A 422 here means "return to
  step 2," never "retry step 3."
- **F3 — bounce.** Do not resend to the same address. Surface the
  bounce reason from the webhook payload.

Notice what carries the weight: the state table is implicit in the step text (key.token → auth header, domain.id → step 3, sender.id → step 4), the wait state in step 2 is explicit so the agent knows polling is expected behavior rather than an error, and every failure exit names the step to return to. The 422 in step 3 is the single most valuable line in the doc — it converts the exact error an agent will hit into a navigation instruction. For the individual pieces referenced here, the glossary covers webhooks and API authentication in depth.

Where workflow docs live

A workflow doc an agent cannot find might as well be unwritten. Three placements determine whether it is on the agent's path.

A guides section on the plain-fetch docs surface. The workflow needs its own URL, server-rendered, reachable without JavaScript execution — the same bar every page of agent-facing documentation has to clear. Guides buried inside a client-rendered docs app fail the fetch before an agent reads a word.

Linked from llms.txt. An llms.txt file is the map agents check first, and 64% of the APIs in the Discry Index corpus now publish one. A map that lists only reference pages reproduces the reference-only problem at the discovery layer: the agent finds fifty endpoint pages and no path through them. Put the workflow guides in their own section of the file, near the top. The llms.txt article covers structure; the signal page covers how Discry checks it.

As the golden path in AGENTS.md. An AGENTS.md file — the convention documented at agents.md — is instructions addressed directly to coding agents, and it is the natural home for the one workflow that matters most: the golden path from empty project to first successful call. Only 30% of the corpus ships one, which makes it one of the cheapest differentiating moves on the discovery surface. AGENTS.md for APIs covers the format in full.

Your OpenAPI spec does real work here too, in a supporting role: an operation description that says "requires a verified domain — see the sending workflow" plants a pointer at exactly the spot where an agent working from the spec alone would otherwise guess.

Anti-patterns

Four placements recur across the corpus that look like workflow documentation and fail agents anyway.

Workflows only in blog posts. The launch post that walks through the full integration is often the best sequence writing the company ever produced — and it lives off the docs path, unlinked from llms.txt, dated 2024, describing a deprecated auth flow. Blog posts rot; workflow docs are maintained surface. If the post is the only place the sequence exists, the sequence is effectively undocumented.

Workflows only in SDKs. A quickstart script in an examples/ directory encodes the ordering in code, in one language, in a repository the agent may never fetch. The plain-HTTP docs surface — the thing agents actually read — never states the sequence. The SDK is a delivery mechanism for the workflow; it cannot be the sole record of it.

Implied-but-unwritten orderings. The most common pattern of all: the only place the ordering appears is an error table. The reference page for the send endpoint lists 422 domain_not_verified among its errors, and that one row is the entire documentation of the fact that domain verification precedes sending. A human reads that row and reconstructs the sequence; an agent hits the error at runtime, mid-task, with tokens already spent. Every "must first" hidden in an error message is a workflow doc that was never written.

Happy-path-only guides. A numbered list of calls with no wait states and no failure exits documents the demo, and the demo is the one run that never happens in production.

How this shows up in the measurement

Discry measures comprehension behaviorally: real models are quizzed against your live docs, including request-construction tasks that require assembling correct calls from what the documentation actually says. An API whose docs carry real sequence gives a model something to follow; an API that documents endpoints in isolation forces the model to improvise the chain, and improvised chains are where invented parameters and phantom orderings surface. The methodology describes how those tasks are built and graded — mechanically, against ground truth cited to your own pages. The practical takeaway sits upstream of any measurement: write the sequence down, put it where the maps point, and the agent executes your path instead of one it made up. The prioritized checklist places workflow docs among the rest of the agent-readiness work.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.