Mermaid Sequence Diagrams for API Documentation
Use Mermaid sequence diagrams to explain API requests, authentication, service boundaries, and asynchronous responses.
By Mermaid Studio Team · Published August 2, 2026 · Updated August 2, 2026
Why API documentation needs a sequence
An endpoint reference tells readers what an API accepts and returns. A sequence diagram explains when the call happens, which service owns each step, and how authentication or retries affect the request.
Use it for flows that cross more than one boundary, such as a browser calling an API that then calls an identity provider or payment service.
Show the request and response path
Declare the actors and participants first, then add messages in execution order. Keep each message focused on one interaction.
Authenticated API request
sequenceDiagram
actor User
participant Web
participant Auth
participant API
User->>Web: Save project
Web->>Auth: Request session token
Auth-->>Web: Session token
Web->>API: PATCH /projects/:id
API-->>Web: Saved project
Web-->>User: Show confirmationDocument failure paths without overwhelming the reader
Add notes for important assumptions and use alternative blocks when the error path changes the behavior. Avoid including every log line or internal function call; link to a lower-level document when readers need more detail.
For asynchronous work, make the queue, worker, callback, or event visible so the reader understands where the original request ends.
Review the diagram with the API owner
The most useful sequence diagrams are reviewed alongside the implementation. Start from the API documentation page, then open the sequence editor when you need to revise participants or export the result.