Mermaid Sequence Diagram Syntax

What a Mermaid sequence diagram is for

A sequence diagram shows how participants (users, services, databases) exchange messages over time, top to bottom. It is the usual way to document an API call chain, an OAuth flow or a retry protocol.

Sequence Diagram syntax

Basic example

sequenceDiagram
    autonumber
    actor U as User
    participant A as App
    participant S as Auth Server
    U->>A: Click "Sign in"
    A->>S: Redirect to /authorize
    S-->>U: Login page
    U->>S: Credentials
    S-->>A: Authorization code
    A->>S: Exchange code for token
    S-->>A: Access token
    A-->>U: Signed in

Open this example in the Mermaid editor

More sequence diagram examples

API call with cache and error handling

alt/else shows the two outcomes; + and - draw activation bars on the API.

sequenceDiagram
    participant C as Client
    participant API
    participant R as Redis
    participant DB as Database
    C->>+API: GET /users/42
    API->>R: GET user:42
    alt cache hit
        R-->>API: user JSON
    else cache miss
        R-->>API: nil
        API->>DB: SELECT * FROM users WHERE id = 42
        DB-->>API: row
        API-)R: SET user:42 (async)
    end
    API-->>-C: 200 OK

Open “API call with cache and error handling” in the editor

Retries with a loop and notes

loop wraps repeated messages; notes explain timing without adding participants.

sequenceDiagram
    participant W as Worker
    participant Q as Queue
    participant S as Payment Service
    W->>Q: Receive job
    loop Up to 3 attempts
        W->>S: POST /charge
        S--xW: 503 Service Unavailable
        Note over W: Wait 2^n seconds
    end
    W->>Q: Move job to dead-letter queue

Open “Retries with a loop and notes” in the editor

Common mistakes

• The word end inside a message breaks the diagram the same way it does in flowcharts. Wrap it: A->>B: (end) or use "End".
• Use ->> for requests and -->> for responses; readers expect solid calls and dotted replies.
• Semicolons end statements, so write #59; for a literal semicolon in message text.

Use it in Markdown

```mermaid
sequenceDiagram
    autonumber
    actor U as User
    participant A as App
    participant S as Auth Server
    U->>A: Click "Sign in"
    A->>S: Redirect to /authorize
    S-->>U: Login page
    U->>S: Credentials
    S-->>A: Authorization code
    A->>S: Exchange code for token
    S-->>A: Access token
    A-->>U: Signed in
```

GitHub, GitLab, Azure DevOps, Obsidian, Notion and docs generators such as Docusaurus and MkDocs (with a plugin) draw fenced mermaid blocks. Check it locally in the Markdown preview.

Other Mermaid diagrams

• Mermaid flowchart syntax
• Mermaid class diagram syntax
• Mermaid state diagram syntax
• Mermaid er diagram syntax
• Mermaid gantt chart syntax
• Mermaid pie chart syntax
• Mermaid mindmap syntax
• Mermaid timeline syntax
• Mermaid git graph syntax
• Mermaid user journey syntax
• Mermaid quadrant chart syntax
• Mermaid xy chart syntax

Sources

• Mermaid docs: Sequence Diagram

Spotted a mistake? Email hello@devtoolsmith.com and we’ll fix it.

Frequently asked questions