How to Document API Flows in Confluence With Mermaid Sequence Diagrams

The OpenAPI file was complete.

Every endpoint had a path, method, and schema. During design review, the platform lead still asked the question the spec did not answer cleanly:

"What happens first — and who calls whom when checkout fails?"

Endpoint catalogs describe shape. Mermaid sequence diagrams Confluence pages describe order: requests, responses, async handoffs, retries, and failure branches between named systems.

This how-to walks through a practical API sequence diagram Confluence workflow: choose sequence syntax over flowcharts, define stable participant names, model error paths beside the happy path, preview while you edit, and hand the diagram to reviewers who were not in the authoring session.

Quick Answer

• Use sequenceDiagram for API flows. When the question is call order, sequence syntax beats flowcharts.
• Stabilize participant IDs early. Use short machine-friendly IDs with readable display labels so diffs and search stay useful.
• Put success and failure in one diagram. Use alt, opt, loop, and par so error stories do not drift into prose-only sections.
• Preview while editing. Any Confluence Mermaid API documentation macro with live preview catches syntax and layout problems before review.
• Hand off with numbered steps and exports. autonumber, Mermaid source, and SVG give reviewers a shared vocabulary.

BacklogBridge Diagram Lens for Confluence is one macro built for source-first Mermaid with Confluence Mermaid live preview, wide reader, search, and export. Verify the current Marketplace listing before install.

What You Are Trying To Accomplish

You want Confluence pages that explain how services interact over time:

• which system sends the first request
• which dependencies are synchronous vs async
• what the caller receives on success
• what happens on validation failure, timeout, or downstream outage
• how retries, idempotency, or compensating actions fit the flow

The outcome is a review artifact stakeholders can discuss without the author narrating from memory.

Place the diagram on the same page as the API overview or operation section it explains — above request/response tables when order matters, beside webhook or async event notes when callbacks are part of the story. Sequence diagrams complement OpenAPI and AsyncAPI specs; they do not replace machine-readable contracts.

Requirements

Why Sequence Diagrams Fit API Flows

The Mermaid documentation describes diagrams defined as text and code. For APIs, the important dimension is time.

Backlog Bridge's Mermaid chart tips guide recommends sequenceDiagram when the diagram must show request order, responses, async work, retries, and failures.

Map API Concerns To Sequence Constructs

Step 1: Define Stable Participants

Start with participants that match how engineers talk about the system — but separate stable IDs from display labels.

sequenceDiagram
    actor actor_client as Client app
    participant svc_gateway as API Gateway
    participant svc_orders as Orders Service
    participant db_orders as Orders DB

If a service is renamed, update the alias first. Reviewers see the new name; diffs stay small.

Backlog Bridge's knowledge-base guidance also recommends predictable prefixes when teams use AI tools to revise Mermaid source — the same naming rules help human reviewers.

Step 2: Draft The Happy Path With autonumber

Add the success path before error branches. Use autonumber when reviewers need to reference exact steps in comments, tickets, or incident notes.

sequenceDiagram
    autonumber
    actor actor_client as Client app
    participant svc_gateway as API Gateway
    participant svc_orders as Orders Service
    participant db_orders as Orders DB

    actor_client->>svc_gateway: POST /checkout
    svc_gateway->>svc_orders: Create order command
    svc_orders->>db_orders: INSERT order row
    db_orders-->>svc_orders: order_id
    svc_orders-->>svc_gateway: 201 Created
    svc_gateway-->>actor_client: 201 Created

Use solid arrows (->>) for requests and dashed arrows (-->>) for responses, following Mermaid sequence diagram syntax.

Keep message text short: HTTP method and path, command name, or domain event — not paragraph-length payloads or secret values.

Minimum viable diagram, then failure depth

Teams new to Mermaid API documentation should ship in two passes:

1. Minimum viable: participants, happy path, autonumber, one Note for auth or idempotency if needed.
2. Failure depth: add one alt block per major failure class — validation, dependency timeout, authorization — then optional loop or opt for retries.

That keeps preview cycles fast and gives reviewers something concrete early.

Step 3: Add Error, Retry, And Parallel Paths

Model failures beside success so the diagram stays the system of record.

sequenceDiagram
    autonumber
    actor actor_client as Client app
    participant svc_gateway as API Gateway
    participant svc_orders as Orders Service
    participant db_orders as Orders DB

    actor_client->>svc_gateway: POST /checkout
    Note over actor_client,svc_gateway: Idempotency-Key required
    svc_gateway->>svc_orders: Create order command

    alt Valid payload
        par Reserve inventory
            svc_orders->>svc_orders: Check stock
        and Quote price
            svc_orders->>svc_orders: Calculate total
        end
        svc_orders->>db_orders: INSERT order row
        db_orders-->>svc_orders: order_id
        svc_orders-->>svc_gateway: 201 Created
        svc_gateway-->>actor_client: 201 Created
    else Validation failed
        svc_orders-->>svc_gateway: 422 Unprocessable
        svc_gateway-->>actor_client: 422 Unprocessable
    else Database unavailable
        svc_orders-->>svc_gateway: 503 Service unavailable
        svc_gateway-->>actor_client: 503 Service unavailable
    end

    opt Retry policy enabled
        loop Up to 3 attempts
            actor_client->>svc_gateway: POST /checkout (retry)
            svc_gateway->>svc_orders: Create order command
        end
    end

Split into a second diagram when one flow mixes checkout, fulfillment, and billing settlement. One diagram should answer one review question.

For accessibility on shared API docs, add accTitle and accDescr when your Mermaid renderer supports them on sequence diagrams.

Step 4: Edit With Live Preview In Confluence

Syntax errors are cheaper to fix while authoring than during a review meeting.

After an admin installs an approved Mermaid macro, use this loop:

1. Paste a minimal happy-path skeleton.
2. Validate with a small known-good sample if the macro exposes a syntax panel.
3. Confirm participants render with readable aliases.
4. Add autonumber once message order is stable.
5. Introduce one alt block at a time; preview after each addition.
6. Open wide view if lifelines crowd the page column.
7. Save, reopen, and confirm stored configuration renders the same way.

Diagram Lens public pages describe a source editor with live preview, line/character counts for source size, and a wide reader with search and minimap for longer diagrams. Diagram Lens support docs also recommend starting from a small known-good diagram and checking the syntax error panel for line, column, and token details when render fails.

That is the practical value of Confluence Mermaid live preview: the diagram and surrounding spec stay in one place, and authors see layout problems before review.

Step 5: Hand Off For Review

Review handoff fails when only the author can narrate the flow.

Suggested review agenda:

1. Confirm participant names match the service catalog.
2. Walk the happy path by step number.
3. For each alt branch, confirm status codes and owning team.
4. Mark async or out-of-band work intentionally off-diagram.
5. Record open questions as page comments.

Example reviewer comment that works because of autonumber:

"Step 6 should return 409 when the idempotency key repeats, not 422."

Diagram Lens public support docs describe Mermaid source and SVG as primary reliable export paths. PNG, PDF, and clipboard image export are best effort and may depend on browser support, diagram size, and Forge iframe permissions — verify on your largest real diagram if raster exports matter.

Common Pitfalls

Backlog Bridge's knowledge-base page notes that Diagram Lens-safe examples avoid source-defined interactivity and raw markup patterns — appropriate for API documentation in shared Confluence spaces.

Admin Checks Before Rollout

Atlassian's Manage your apps documentation says Confluence apps are usually installed from Marketplace through Connected Apps and require site admin access.

At the time of research on July 13, 2026, I did not find an official Atlassian Marketplace listing for BacklogBridge Diagram Lens for Confluence through available public sources. Search Marketplace again before install.

The public Diagram Lens security page describes client-side rendering, storage:app scope, no external egress declared in the current manifest, and strict Mermaid sanitization. For a fuller macro security review, see Mermaid Macro Security in Confluence.

Do not infer SOC 2, ISO, Cloud Fortified, GDPR/DPA, or procurement approval without explicit published evidence.

When To Use A Different Approach

• OpenAPI-only reference pages may be enough when readers never ask about ordering.
• Event schemas and topic diagrams may fit async platforms better than request/response sequences alone.
• Canvas tools such as draw.io or Gliffy may fit workshop sketching better than maintained text source — see Mermaid vs draw.io and Gliffy in Confluence.
• Static images may be enough for rarely changed flows with no source review requirement.

Choose sequence diagrams when call order is debated repeatedly and the diagram should change with the spec.

Trial Checklist

Test with one real API flow your team argues about — not a toy two-box diagram.

1. Create a Confluence page beside the relevant API spec section.
2. Insert the Mermaid macro and define stable participants.
3. Draft the happy path; enable autonumber.
4. Add at least one validation failure and one downstream failure with alt.
5. Preview after each structural change; fix syntax with the macro's error panel if available.
6. Open wide view and search for two participant labels reviewers name often.
7. Ask a second reviewer to explain one numbered step without author guidance.
8. Export Mermaid source and SVG; test PNG only if your handoff requires it.

Final Recommendation

Mermaid sequence diagrams Confluence workflows work best when teams treat API flows as time-ordered, reviewable source — not as one-off drawings.

Define stable participants, number the happy path, model failures beside success, preview while editing, and hand reviewers numbered steps plus source or SVG exports. If your team already keeps Mermaid in Confluence and wants live preview plus reader tools for longer API flows, Diagram Lens is worth a focused trial — after you verify the current Marketplace listing, install prompt, and export behavior on your own diagrams.

For diagram-type guidance, see Backlog Bridge's Mermaid chart tips guide. For large-diagram reading beyond sequence layout, see Mermaid Diagrams in Confluence: Why Big Diagrams Need a Reader.