Agent

API Flow Visualizer

apisequence diagramdocumentation

API Flow Visualizer: Document Your API Interactions

Sequence diagrams make complex API interactions understandable. This AI agent creates clear, professional diagrams showing request/response flows between services.

Full Prompt
Create a detailed sequence diagram in Mermaid syntax that precisely models an API flow including request/response payloads, authentication, error handling, and asynchronous operations.

SEQUENCE DIAGRAM PROCESS:

1. Flow Analysis
   - Identify all actors and services that participate in the flow (user, browser, API gateway, microservices, databases, external APIs)
   - Determine the trigger event that initiates the flow
   - Map the complete happy path from initiation to final response
   - Identify all branching points: conditionals, error paths, retry logic
   - Determine which operations are synchronous vs. asynchronous (fire-and-forget, event-driven, webhook callbacks)

2. Authentication and Authorization Modeling
   - Show token acquisition or session establishment if it is part of this flow
   - Show where tokens are validated and by which service
   - Model token refresh flows if applicable
   - Show authorization checks (role verification, permission checks) at the appropriate service boundary
   - Indicate what happens when auth fails (401/403 responses)

3. Payload Design
   - Include simplified but realistic request payloads at each service boundary (not every internal call)
   - Show response payloads for both success and error cases
   - Include HTTP status codes with each response arrow
   - Show headers that are architecturally significant (Authorization, Content-Type, correlation IDs)

4. Error Path Modeling
   - Model at least the 2-3 most important error scenarios as alt blocks
   - Show error propagation: how an error in a downstream service surfaces to the caller
   - Include timeout handling and retry logic if applicable
   - Show compensation or rollback actions for failed multi-step operations
   - Model circuit breaker behavior if relevant

5. Asynchronous Operations
   - Distinguish sync calls (solid arrows) from async events (dashed arrows) using Mermaid syntax
   - Show message queues or event buses as explicit participants
   - Model callback or webhook flows with clear temporal ordering
   - Show parallel operations using par blocks where applicable
   - Indicate background jobs or scheduled tasks triggered by the flow

6. Diagram Quality
   - Use activate/deactivate to show when each participant is processing
   - Add notes for complex business logic that cannot be expressed as simple messages
   - Use loop, alt, opt, and par blocks to model control flow clearly
   - Keep message labels concise but precise (include HTTP method and path for API calls)

OUTPUT CONSTRAINTS:
- Produce valid Mermaid sequence diagram syntax that renders without errors
- Include at minimum: the happy path AND one error/alternate path
- Every message arrow must have a descriptive label
- Payloads should be simplified to key fields only (3-5 fields), not full schemas
- If information about error handling or auth is not provided, include reasonable defaults and mark with [ASSUMED]
- Add a written description of the flow below the diagram for context

FORMAT:
## Sequence Diagram: [Flow Name]

### Overview
[1-2 paragraph description of the flow, when it is triggered, and its outcome]

### Diagram
```mermaid
sequenceDiagram
    [complete diagram code]
```

### Flow Description
[Step-by-step numbered walkthrough of the happy path]

### Error Scenarios
[Description of each error path shown in the diagram and how it is handled]

### Payloads Reference
[Table or JSON blocks showing the full request/response schemas for key interactions]

### Notes
[Assumptions, edge cases, or design decisions worth documenting]

---

MY INFO:

Flow Name (e.g., "User Authentication" or "Order Processing"): (required)

Actors/Services Involved: (required)
1.
2.
3.
4.

Step-by-Step Flow: (required)
1.
2.
3.

Authentication Mechanism (JWT, OAuth2, API key, session): (optional)

Known Error Scenarios to Include: (optional)

Asynchronous Operations (background jobs, events, webhooks): (optional)

Protocol Details (REST, gRPC, GraphQL, WebSocket): (optional)

What's Visualized

  • Request/Response Flows: Complete data path
  • Authentication: Token flow and validation
  • Error Handling: Failure scenarios and fallbacks
  • Async Operations: Background jobs and callbacks

Output Formats

  • Mermaid syntax (GitHub-compatible)
  • PlantUML format
  • Visual diagram image
  • Exportable for documentation

Use Cases

  • API Documentation: Show how endpoints interact
  • Onboarding: Help new developers understand flows
  • Debugging: Trace request paths
  • Design Reviews: Validate architecture decisions

Best Practices

  1. Keep diagrams focused on one flow
  2. Include error paths
  3. Show timing for async operations
  4. Label all data exchanges

Create diagrams that make complex systems understandable.