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/agent/playground

Headers:

Authorization: Bearer <jwt-from-auth>
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}",
  "ttlDays": 14
}

Response:

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

• • 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 prevents low-quality public diagrams from being indexed or shared unintentionally.

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 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 }.
• 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 {
  n1: circle label:"Start"
  n2: rectangle label:"Submit Order"
  n3: rectangle label:"Receive Order"
  n4: circle label:"Complete"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> sales.n5.handle(top)
  n3.handle(right) -> n4.handle(left)
}

sales {
  n5: rectangle label:"Review Order"
  n6: diamond label:"Approve Order?"
  n7: rectangle label:"Process Order"
  n5.handle(right) -> n6.handle(left)
  n6.handle(right) -> n7.handle(left) [label:"Yes"]
  n7.handle(bottom) -> n8.handle(top)
  n6.handle(top) -> customer.n2.handle(right) [label:"No"]
}

fulfillment {
  n8: rectangle label:"Ship Order"
  n9: diamond label:"Delivered?"
  n10: rectangle label:"Mark Complete"
  n8.handle(right) -> n9.handle(left)
  n9.handle(right) -> n10.handle(left) [label:"Yes"]
  n10.handle(top) -> customer.n3.handle(bottom)
  n9.handle(bottom) -> n8.handle(bottom) [label:"No, Retry"]
}

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/agent/playground \
  -H "Authorization: Bearer your-jwt-token-here" \
  -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}",
    "ttlDays": 7
  }'

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" },
        "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
      },
      "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" },
      "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
    },
    "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