API Reference - WhizAI Documentation

Base URL

https://api.whizur.ai/v1

Local development: http://localhost:3000/v1

Authentication

Include your API key on every request. Two header formats are accepted:

API key header:

X-API-Key: cw_dev_YOUR_KEY_HERE

Bearer token format:

Authorization: Bearer cw_dev_YOUR_KEY_HERE

Regular API keys cannot execute workflows directly

Calling workflow execution routes with a regular cw_dev_* or cw_prod_* key returns 403 WORKFLOW_EXECUTION_FORBIDDEN. Use POST /v1/capabilities/:id/execute instead.

Learn more about API keys and security →

Response Format

All responses use a consistent envelope:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "errors": [{ "field": "input.prompt", "code": "REQUIRED" }]
}

Endpoints

Capabilities

GET /v1/capabilities

List all capabilities available to your app.

GET /v1/capabilities/:id

Get a single capability definition, including its input schema.

POST /v1/capabilities/:id/execute

Execute a capability. Returns a runId immediately; poll GET /v1/workflow-runs/:id for status.

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 mountain at dawn", "size": "1024x1024" } }'

POST /v1/capabilities/:id/dry-run

Validate capability input against the schema without executing. Returns validation errors or a preview of what would be sent.

Workflow Runs

GET /v1/workflow-runs/:id

Get the status and output of a run. Poll this endpoint until status is completed or failed.

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

Artifacts

GET /v1/artifacts/:id

Retrieve a single artifact by ID. Returns the download URL, MIME type, size, and provenance (run ID, step ID, parent artifact ID).

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

Triggers

GET /v1/triggers

List all triggers configured for your app.

POST /v1/triggers

Create a trigger — schedule a capability to run on a cron or in response to an event.

GET /v1/triggers/:id

Get a single trigger by ID.

PATCH /v1/triggers/:id

Update a trigger (schedule, input, or enabled state).

DELETE /v1/triggers/:id

Delete a trigger.

Rate Limits

Limits are applied per app using a token-bucket algorithm. Response headers tell you where you stand:

X-RateLimit-Limit — requests allowed per window

X-RateLimit-Remaining — requests left in current window

X-RateLimit-Reset — Unix timestamp when the window resets

Error Codes

Code	HTTP Status	Description
`INPUT_VALIDATION_FAILED`	400	Request body failed schema validation
`UNAUTHORIZED`	401	Missing or invalid API key
`WORKFLOW_EXECUTION_FORBIDDEN`	403	Regular API keys cannot call workflow execution endpoints directly — use capabilities
`NOT_FOUND`	404	Resource not found
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded; retry after `X-RateLimit-Reset`
`INTERNAL_ERROR`	500	Internal server error

Want More?

The interactive OpenAPI viewer at /app/api-docs lets you explore the full schema and try requests live.

Getting Started Workflows →