pokee logo

Pokee AI Workflow Streaming API Documentation

Overview

The Workflow Streaming API lets you run workflows and receive real-time updates via Server-Sent Events (SSE). Use /run_workflow_api  to start a workflow (with optional streaming) or  /stream_workflow_api to attach to an existing one. Events show task progress, status changes, output generation, and final results.

Run Workflow API

Endpoint: /run_workflow_api

Purpose: Execute a workflow with optional SSE streaming

Request

  • Method: POST
  • Authentication: Bearer token (Authorization header)

Body:

{
  "seed_workflow_id": 123,
  "user_id": "user123",
  "input_data": {},
  "has_manual_approval": true,
  "has_manual_output_approval": true,
  "stream": true
}

Parameters:

  • seed_workflow_id (required): Workflow template ID
  • user_id (required): User ID
  • input_data (optional): Workflow input parameters
  • has_manual_approval (optional, default: true): Enable task approval
  • has_manual_output_approval (optional, default: true): Enable output approval
  • stream (optional, default: false): ⚡ Determines response format
    • true / "true" / "1" / "yes" → SSE streaming response
    • false / omitted → JSON confirmation response

Response Format:

  • ✅ stream=true: Real-time SSE stream with progress updates (see event types below)
  • ✅ stream=false: JSON response confirming workflow execution started (does not wait for completion)

Stream Workflow API

Endpoint: /stream_workflow_api

Purpose: Stream updates for an already-running workflow

Request

  • Method: POST
  • Authentication: Bearer token (Authorization header)

Body:

{
  "workflow_id": 456,
  "user_id": "user123"
}

Parameters:

  • workflow_id (required): Running workflow ID
  • user_id (required): User ID

Response: SSE stream with real-time updates

SSE Event Types

All events follow this format:

event: <event_name>
data: <JSON_object>

1. task_progress_update

Real-time task output chunks

{
  "event": "task_progress_update",
  "timestamp": "20251027173836",
  "data": {
    "message": {
      "type": "chunk",
      "content": "Generated content..."
    },
    "task_index": 6,
    "task_id": 403931,
    "stream_type": "output"
  }
}

2. task_status_update

Task completion status

{
  "event": "task_status_update",
  "timestamp": "20251027173837",
  "data": {
    "task_id": 403930,
    "status": "success",
    "error_data": null
  }
}

3. workflow_output_generation_started

Output generation phase begins

{
  "event": "workflow_output_generation_started",
  "timestamp": "20251027173843",
  "data": "Starting workflow output generation"
}

4. workflow_output_generation_finished

Output generation phase completes

{
  "event": "workflow_output_generation_finished",
  "timestamp": "20251027173856",
  "data": "Finished workflow output generation"
}

5. workflow_update

Complete workflow results

{
  "event": "workflow_update",
  "timestamp": "20251027173856",
  "data": {
    "workflow_id": 30459,
    "status": "success",
    "workflow_output": {
      "output_data": {
        "social_media_posts": [...]
      }
    }
  }
}

6. workflow_finish

Workflow execution complete

{
  "event": "workflow_finish",
  "timestamp": "20251027173857",
  "data": "All tasks complete"
}

Event Flow

  1. Task Execution Phase
    • Multiple task_progress_update events (streaming output chunks)
    • task_status_update for each completed task
  2. Output Generation Phase
    • workflow_output_generation_started
    • workflow_output_generation_finished
  3. Completion Phase
    • workflow_update (final results)
    • workflow_finish

Error Handling

Insufficient Credits (529):

{
  "error": "Your credit balance is insufficient. Please add credits to continue.",
  "insufficient_credits": true
}

Access Denied (403):

{
  "error": "Access denied: You don't have permission to access this workflow"
}

Validation Failed (400):

{
  "error": "seed_workflow_id and user_id required"
}

Connection Settings (Server-Side)

These are automatically set by the server in response headers. Clients do not need to configure these.

  • Timeout: 1800 seconds (30 minutes)
  • Content-Type: text/event-stream
  • Keep-Alive: timeout=1800, max=2000
  • Cache-Control: no-cache, no-transform, no-store

Client Requirements:

  • Handle SSE (Server-Sent Events) stream format
  • Include Bearer token in Authorization header