Workflows

Capabilities are your interface. A Run tracks every execution behind the scenes.

How It Works

The WhizAI platform separates what you want to do from how it gets done. You call a Capability — a stable, versioned interface — and the platform handles the underlying multi-step orchestration for you.

Every capability execution creates a Run that tracks the full lifecycle: pending → running → completed (or failed). You can poll the run to get status and retrieve output artifacts when the work is done.

Capabilities Are the Interface

Regular API keys can only call capability endpoints — not workflow execution endpoints directly. This is intentional: capabilities provide a stable, versioned contract so your integration stays consistent as the platform evolves internally.

Important: Direct workflow execution is blocked

Calling workflow execution endpoints directly with a regular API key returns 403 WORKFLOW_EXECUTION_FORBIDDEN. Use the capability execute endpoint instead: POST /v1/capabilities/:id/execute.

Execute a capability:

curl -X POST https://api.whizur.ai/v1/capabilities/image-generate-v1/execute \
  -H "X-API-Key: cw_dev_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "A beautiful sunset over the ocean",
      "size": "1024x1024"
    }
  }'

Response includes a runId and a status field. Execution is asynchronous — poll the run to get the final result.

Polling for Completion

Use the SDK or poll the run endpoint directly until status is completed or failed.

SDK (recommended):

import { WhizuraiClient } from '@whizurai/sdk-js'

const client = new WhizuraiClient({ apiKey: process.env.WHIZURAI_API_KEY })

const run = await client.capabilities.run('image-generate-v1', {
  prompt: 'A beautiful sunset over the ocean',
  size: '1024x1024',
})

const result = await client.runs.pollUntilDone(run.id)
console.log(result.artifacts)

REST polling:

curl https://api.whizur.ai/v1/workflow-runs/run_abc123 \
  -H "X-API-Key: cw_dev_YOUR_KEY_HERE"

Poll until status is completed or failed. Typical poll interval: 1–3 seconds.

Run Lifecycle

Every run transitions through these states:

pending

Run created, queued for execution

running

Steps are executing

completed

All steps succeeded — artifacts are available

failed

A step failed — check the run's error field

Retrieving Artifacts

When a run completes, its output artifacts are listed in the run response under artifacts. Fetch a specific artifact by ID:

curl https://api.whizur.ai/v1/artifacts/art_xyz789 \
  -H "X-API-Key: cw_dev_YOUR_KEY_HERE"

Artifacts include a download URL, MIME type, size, and full provenance (which run and step produced them).

Triggering Runs Automatically

Use the Triggers API (/v1/triggers) to schedule runs or fire them on events — without writing polling code yourself. Triggers support cron schedules and webhook-based activation.

See the API Reference for trigger endpoints →

Next Steps

Full API ReferenceReview Core Concepts →