Complete guide for AI agents and bots to integrate with FlowZap's diagram creation API

Quick Start

Think of this as your 3-step process to get started with FlowZap's Agent API.

1. Register Your Agent - Get your API token by registering your agent
2. Authenticate - Exchange your API token for a short-lived JWT
3. Create Diagrams - Create a diagram in a project; use Playground to share FlowZap Code via public URL

API Endpoints

Agent Registration

POST https://flowzap.xyz/api/agent/register

Request Body:

{
  "name": "Your Agent Name",
  "email": "agent@example.com",
  "termsAccepted": true
}

Response:

{
  "success": true,
  "user": {
    "id": "user-id",
    "email": "agent@example.com"
  },
  "apiToken": "your-api-token",
  "tokenType": "Bearer",
  "expiresAt": "2025-08-01T12:00:00Z"
}

Authentication

POST https://flowzap.xyz/api/agent/auth

Request Body:

{
  "apiToken": "your-api-token-from-registration"
}

Response:

{
  "success": true,
  "accessToken": "jwt-token",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Create Diagram

POST https://flowzap.xyz/api/agent/diagrams

Headers:

Authorization: Bearer <jwt-from-auth>
Content-Type: application/json

Request Body:

{
  "name": "User Registration Process",
  "projectId": "project-id",
  "colorScheme": "purple"
}

Response:

{
  "success": true,
  "data": {
    "diagram": {
      "id": "diagram-id",
      "name": "User Registration Process",
      "colorScheme": "purple",
      "createdAt": "2025-08-13T12:00:00.000Z",
      "project": { "id": "project-id", "name": "Default Project" }
    }
  },
  "agent": { "id": "agent-user-id", "email": "agent@example.com" },
  "attribution": "Powered by FlowZap.xyz"
}

Playground Session (Public URL)

POST https://flowzap.xyz/api/playground/create

Headers:

Content-Type: application/json

Request Body:

{
  "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
  "view": "workflow"
}

Response:

{
  "success": true,
  "url": "https://flowzap.xyz/playground/abcd1234",
  "tokenExpiresAt": "2025-08-20T12:00:00.000Z"
}

• • The URL opens the editor UI in a signed-out, unsaved state with code prefilled.
• • No diagram is saved until the user registers and explicitly saves.
• • This endpoint is rate limited by IP and is intended for anonymous previews and MCP-generated share links.

FlowZap Code Syntax

FlowZap uses its own syntax called "FlowZap Code" for creating business process diagrams.

Layout style and handle rules (for Agent API)

• Lane comment syntax: The lane display label # Label MUST be on the same line as the opening brace: laneName { # Label. Never put it on the next line.
• Lane meaning: View a Lane as a one particular person or system that accomplishes tasks.
• Layout goal: Flows should usually be horizontal, left→right within each lane (BPMN-like). Only use a vertical layout only when specified in a AI Agent or Human users' prompt.
• Define then connect: As seen in the syntax example below, define the components, then connect them: In each lane, first declare shapes; then declare edges.
• Handle usage: Prefer right/left. Use top/bottom only for brief cross-lane transitions or minor alternate branches, then resume horizontal.
• Decisions: Place diamonds inline in the lane. The “Yes/primary” path continues to the right; “No/alternate” can briefly go top/bottom and then return to horizontal.
• Cross-lane edges: From within a lane, reference the other lane’s node as otherLane.node.handle(direction). Keep the vertical hop minimal.
• Alignment: Avoid tall vertical stacks in lanes; keep nodes aligned horizontally to reduce top/bottom edges.
• Edge syntax (exact): node.handle(direction) -> node.handle(direction) [label="Text"] with direction ∈ { right, left, top, bottom }. Note: edge labels use equals ([label="Text"]), while node attributes use colon (label:"Text").
• Sequence diagram quality: Every cross-lane request must have a matching response edge before the next major request begins. Define cross-lane edges in chronological order. Keep a strict request → response → next request rhythm. No orphaned nodes (every node must be in at least one edge). Separate async flows from the main flow.
• Shapes: Don't ever use a Taskbox shape in a workflow, except if the user explicitely requests it in its input.

Basic FlowZap Code Example

1 { # 1
  n1: circle label:"Start"
  n2: rectangle label:"Brainstorm ideas with AI"
  n3: diamond label:"Anyone of them any good?"
  n4: rectangle label:"Analyze the idea much more."
  n5: rectangle label:"Find new ideas. Brainstorming with AI can be endless."
  n6: circle label:"End"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
  n3.handle(top) -> n4.handle(left) [label="Yes"]
  n3.handle(bottom) -> n5.handle(left) [label="No"]
  n4.handle(right) -> n6.handle(left)
  n5.handle(right) -> n6.handle(left)
}

3 Lanes Example

customer { # Customer
  n1: circle label:"Start"
  n2: rectangle label:"Submit Order"
  n3: rectangle label:"Receive Approval"
  n4: circle label:"Complete"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> sales.n5.handle(top)
  n3.handle(right) -> n4.handle(left)
}

sales { # Sales
  n5: rectangle label:"Review Order"
  n6: rectangle label:"Approve Order"
  n7: rectangle label:"Submit to Fulfillment"
  n8: rectangle label:"Receive Fulfillment Update"
  n5.handle(right) -> n6.handle(left)
  n6.handle(top) -> customer.n3.handle(bottom) [label="Approved"]
  n6.handle(right) -> n7.handle(left)
  n7.handle(bottom) -> fulfillment.n9.handle(top)
  n8.handle(right) -> n10.handle(left)
}

fulfillment { # Fulfillment
  n9: rectangle label:"Ship Order"
  n10: rectangle label:"Return Tracking"
  n9.handle(right) -> n10.handle(left)
  n10.handle(top) -> sales.n8.handle(bottom)
}

Complete cURL Examples

1. Register Agent

curl -X POST https://flowzap.xyz/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Assistant",
    "email": "my-assistant@agents.flowzap.xyz",
    "termsAccepted": true
  }'

2. Authenticate

curl -X POST https://flowzap.xyz/api/agent/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "your-api-token-here"
  }'

3. Create Diagram

curl -X POST https://flowzap.xyz/api/agent/diagrams   -H "Authorization: Bearer your-jwt-token-here"   -H "Content-Type: application/json"   -d '{
    "name": "Customer Onboarding",
    "projectId": "project-id",
    "colorScheme": "purple"
  }'

4. Create Playground Session (Public URL)

curl -X POST https://flowzap.xyz/api/playground/create   -H "Content-Type: application/json"   -d '{
    "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
    "view": "workflow"
  }'

SDKs

Install

# Python
pip install flowzap

# JavaScript / TypeScript
npm install @flowzap/agent
# or
pnpm add @flowzap/agent

Python example

from flowzap import FlowzapClient

client = FlowzapClient(base_url="https://flowzap.xyz", timeout_ms=10000, retries=3)

# 1) Register
reg = client.register_agent(name="Acme Bot", email="bot@acme.com", terms_accepted=True)
api_token = reg["apiToken"]

# 2) Authenticate
auth = client.authenticate(api_token)
client.set_access_token(auth["accessToken"])  # for protected endpoints

# 3) Create diagram
created = client.create_diagram(name="Support Flow", project_id="support-ops", color_scheme="slate")
print(created)

# 4) Playground session (public URL to editor with prefilled code)
pg = client.create_playground_session(code="""
lane: Support
node: Start
  text: User opens ticket
""")
print(pg["url"])

JavaScript / TypeScript example

import { FlowzapClient } from "@flowzap/agent";

const client = new FlowzapClient({ baseUrl: "https://flowzap.xyz", timeoutMs: 10000, retries: 3 });

// 1) Register
const reg = await client.registerAgent({ name: "Acme Bot", email: "bot@acme.com", termsAccepted: true });
const apiToken = reg.apiToken;

// 2) Authenticate -> set access token for protected endpoints
const auth = await client.authenticate({ apiToken });
client.setAccessToken(auth.accessToken);

// 3) Create diagram
const created = await client.createDiagram({ name: "Support Flow", projectId: "support-ops", colorScheme: "slate" });
console.log(created);

// 4) Playground session (public URL to editor with prefilled code)
const pg = await client.createPlaygroundSession({ code: 'lane: Support
node: Start
  text: User opens ticket
' });
console.log(pg.url);

Error Handling

• 400 — Validation error (e.g., missing required fields)
• 401 — Invalid or expired token
• 403 — Access denied (e.g., project not accessible)
• 405 — Wrong method (GET on POST-only endpoints)
• 409 — Conflict (e.g., email already registered)
• 429 — Rate limit exceeded
• 500 — Server error

Tool JSON Snippets

OpenAI Tool (Create Playground URL)

{
  "type": "function",
  "function": {
    "name": "flowzap_create_playground",
    "description": "Create a signed-out playground URL prefilled with FlowZap Code.",
    "parameters": {
      "type": "object",
      "properties": {
        "code": { "type": "string", "description": "FlowZap Code content" },
        "view": { "type": "string", "enum": ["workflow", "sequence", "architecture"] }
      },
      "required": ["code"]
    }
  }
}

Anthropic Tool (Create Playground URL)

{
  "name": "flowzap_create_playground",
  "description": "Create a signed-out playground URL prefilled with FlowZap Code.",
  "input_schema": {
    "type": "object",
    "properties": {
      "code": { "type": "string" },
      "view": { "type": "string", "enum": ["workflow", "sequence", "architecture"] }
    },
    "required": ["code"]
  }
}

Best Practices

• Security: Store API tokens securely and never expose them in client-side code
• Rate Limiting: Respect rate limits (currently 10 requests per minute for registration)
• Attribution: Always include "Powered by FlowZap.xyz" when sharing diagrams
• Error Handling: Implement proper error handling for all API calls
• Token Management: JWT tokens expire in 15 minutes - refresh as needed

Support & Resources