API Reference

Workflows API

Run your Fizzly workflows programmatically via REST API. Queue-based execution with webhooks, real-time streaming, and full control over your AI pipelines.

Get API Key Create Workflow

Base URL

https://queue.fizzly.ai

All API endpoints use this base URL. PRO or ULTIMATE subscription required.

Authentication

All API requests must include your API key in the Authorization header. API keys can be created and managed in your account settings.

Header Format

Authorization: Key fiz_your_api_key_here

Example Request

curl https://queue.fizzly.ai/workflows/username/my-workflow \
  -H "Authorization: Key fiz_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"prompt": "A beautiful sunset"}}'

Rate Limiting

API requests are rate limited using a sliding window algorithm. The default limit is 60 requests per minute per API key.

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limitnumber

Maximum requests allowed per window

X-RateLimit-Remainingnumber

Requests remaining in current window

X-RateLimit-Resettimestamp

Unix timestamp when the window resets

429 Too Many Requests

When you exceed the rate limit, you'll receive a 429 response with a Retry-After header indicating how many seconds to wait:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 30
}

Submit Workflow

POST/workflows/{username}/{slug}

Submit a workflow to the execution queue. Returns immediately with a request ID for tracking.

Path Parameters

usernamestring

The workflow owner's username

slugstring

The workflow's URL-friendly slug

Query Parameters

webhookstring (optional)

HTTPS URL to receive completion callback

Request Body

{
  "inputs": {
    "prompt": "A beautiful sunset over the ocean",
    "seed": 12345
  }
}

Response

{
  "request_id": "run_abc123xyz",
  "status": "PENDING",
  "status_url": "https://queue.fizzly.ai/workflows/username/my-workflow/requests/run_abc123xyz/status",
  "response_url": "https://queue.fizzly.ai/workflows/username/my-workflow/requests/run_abc123xyz",
  "cancel_url": "https://queue.fizzly.ai/workflows/username/my-workflow/requests/run_abc123xyz/cancel"
}

Get Status

GET/workflows/{username}/{slug}/requests/{requestId}/status

Poll the current status of a workflow run.

Query Parameters

logsboolean (optional)

Set to 1 to include execution logs

Status Values

IN_QUEUE

Waiting to be processed

IN_PROGRESS

Currently executing

COMPLETED

Finished successfully

FAILED

Execution failed

CANCELLED

Cancelled by user

Response (IN_QUEUE)

{
  "status": "IN_QUEUE",
  "queue_position": 3
}

Response (IN_PROGRESS)

{
  "status": "IN_PROGRESS",
  "progress": 65,
  "current_node": "image-generation"
}

Response (COMPLETED)

{
  "status": "COMPLETED",
  "metrics": {
    "credits_used": 5,
    "total_time_ms": 12500
  }
}

Get Result

GET/workflows/{username}/{slug}/requests/{requestId}

Retrieve the full output of a completed workflow run.

Response

{
  "status": "COMPLETED",
  "outputs": {
    "generated_image": {
      "url": "https://cdn.fizzly.ai/outputs/abc123.webp",
      "width": 1024,
      "height": 1024
    },
    "prompt_used": "A beautiful sunset over the ocean"
  },
  "metrics": {
    "credits_used": 5,
    "total_time_ms": 12500
  },
  "logs": [
    {
      "node": "image-generation",
      "status": "completed",
      "started_at": "2026-01-17T12:00:00Z",
      "completed_at": "2026-01-17T12:00:12Z"
    }
  ],
  "started_at": "2026-01-17T12:00:00Z",
  "completed_at": "2026-01-17T12:00:12Z"
}

Note: Returns 400 Bad Request if the workflow is not yet completed. Use the status endpoint to check completion first.

Cancel Request

PUT/workflows/{username}/{slug}/requests/{requestId}/cancel

Cancel a pending or running workflow request.

Response (Success)

{
  "status": "CANCELLATION_REQUESTED",
  "message": "Request cancellation initiated",
  "previous_status": "PENDING",
  "credits_refunded": 5
}

Response (Already Completed)

{
  "error": "Cannot cancel a completed request",
  "code": "ALREADY_COMPLETED",
  "current_status": "COMPLETED"
}

Credit Refunds: Cancelling a PENDING request refunds all reserved credits. Cancelling a RUNNING request does not refund credits for nodes that have already been processed.

Status Stream (SSE)

GET/workflows/{username}/{slug}/requests/{requestId}/status/stream

Real-time event stream for workflow execution updates using Server-Sent Events.

Event Types

submitevent

Fired when a node starts execution

completionevent

Fired when a node completes with output

outputevent

Fired when the workflow completes with final outputs

errorevent

Fired when the workflow fails

pingevent

Keep-alive event sent every 15 seconds

Example Event Stream

event: submit
data: {"node": "image-generation", "timestamp": "2026-01-17T12:00:00Z"}

event: ping
data: {"timestamp": "2026-01-17T12:00:15Z"}

event: completion
data: {"node": "image-generation", "output": {"url": "https://cdn.fizzly.ai/..."}}

event: output
data: {"outputs": {"generated_image": {"url": "https://cdn.fizzly.ai/..."}}, "credits_used": 5}

JavaScript Example

const eventSource = new EventSource(
  'https://queue.fizzly.ai/workflows/username/my-workflow/requests/run_abc123/status/stream',
  {
    headers: { 'Authorization': 'Key fiz_your_api_key' }
  }
);

eventSource.addEventListener('submit', (e) => {
  console.log('Node started:', JSON.parse(e.data));
});

eventSource.addEventListener('completion', (e) => {
  console.log('Node completed:', JSON.parse(e.data));
});

eventSource.addEventListener('output', (e) => {
  const { outputs } = JSON.parse(e.data);
  console.log('Workflow complete:', outputs);
  eventSource.close();
});

eventSource.addEventListener('error', (e) => {
  console.error('Workflow failed:', JSON.parse(e.data));
  eventSource.close();
});

Webhooks

Instead of polling, you can receive workflow completion notifications via webhook. Pass a ?webhook=URL parameter when submitting your workflow.

Webhook Requirements

Must use HTTPS (HTTP URLs are rejected)
Cannot be internal/private IPs (localhost, 192.168.x.x, 10.x.x.x, etc.)
Must respond within 30 seconds

Webhook Payload

{
  "request_id": "run_abc123xyz",
  "status": "OK",
  "payload": {
    "generated_image": {
      "url": "https://cdn.fizzly.ai/outputs/abc123.webp",
      "width": 1024,
      "height": 1024
    }
  },
  "metrics": {
    "credits_used": 5,
    "total_time_ms": 12500
  },
  "completed_at": "2026-01-17T12:00:12Z"
}

Error Payload

{
  "request_id": "run_abc123xyz",
  "status": "ERROR",
  "error": "Image generation failed: content policy violation",
  "metrics": {
    "credits_used": 0,
    "total_time_ms": 2500
  },
  "completed_at": "2026-01-17T12:00:02Z"
}

Retry Policy

Webhook delivery is retried up to 3 times with exponential backoff:

1st retry: 1 second delay
2nd retry: 2 seconds delay
3rd retry: 4 seconds delay

4xx errors (except 429) are not retried as they indicate client-side issues.

Webhook Headers

User-Agentstring

Fizzly-Webhook/1.0

X-Fizzly-Request-IDstring

The workflow run ID for tracking

Content-Typestring

application/json

Error Codes

The API uses standard HTTP status codes and includes a code field for programmatic error handling.

Status	Code	Description
400	BAD_REQUEST	Invalid request parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	PRO subscription required
404	NOT_FOUND	Workflow or request not found
402	INSUFFICIENT_CREDITS	Not enough credits for workflow
429	RATE_LIMIT_EXCEEDED	Too many requests, retry later
500	INTERNAL_ERROR	Server error, please retry

Error Response Format

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context if available"
  }
}