API Documentation

Integrate Verified Workflows's human-in-the-loop review platform into your workflows.

Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

Authorization: Bearer vw_live_xxxxxxxxxxxxxxxxxxxxxxxx
Workspace-Id: default

Obtaining API Keys

Navigate to Account Settings to create and manage API keys. Each key can be scoped to specific permissions.

Rate Limits

API requests are rate-limited to 5 requests per 10 seconds per API key. When exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header.

Endpoints

curl -X POST https://api.verifiedworkflows.com/v1/tasks \
  -H "Authorization: Bearer hq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Workspace-Id: default" \
  -d '{
    "type": "audio-audit",
    "priority": "express",
    "title": "TTS Quality Check - Batch 42",
    "instructions": "Listen to the audio and verify natural pacing...",
    "payload": {"url": "https://storage.example.com/audio_42.wav"},
    "consensus_total": 3,
    "required_skills": ["audio"]
  }'

import requests

response = requests.post(
    "https://api.verifiedworkflows.com/v1/tasks",
    headers={
        "Authorization": "Bearer hq_live_YOUR_KEY",
        "Content-Type": "application/json",
        "Workspace-Id": "default"
    },
    json={
        "type": "audio-audit",
        "priority": "express",
        "title": "TTS Quality Check - Batch 42",
        "instructions": "Listen to the audio and verify natural pacing...",
        "payload": {"url": "https://storage.example.com/audio_42.wav"},
        "consensus_total": 3,
        "required_skills": ["audio"]
    }
)
task = response.json()
print(f"Task created: {task['id']}")

const response = await fetch('https://api.verifiedworkflows.com/v1/tasks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hq_live_YOUR_KEY',
    'Content-Type': 'application/json',
    'Workspace-Id': 'default'
  },
  body: JSON.stringify({
    type: 'audio-audit',
    priority: 'express',
    title: 'TTS Quality Check - Batch 42',
    instructions: 'Listen to the audio and verify natural pacing...',
    payload: { url: 'https://storage.example.com/audio_42.wav' },
    consensus_total: 3,
    required_skills: ['audio']
  })
});
const task = await response.json();
console.log(`Task created: ${task.id}`);

{
  "status": "created",
  "id": "tsk_live_a3f21",
  "queue_position": 1,
  "payout_escrowed": true,
  "cost_usd": 0.20,
  "consensus_votes_gated": 3,
  "task_created_at": "2026-06-09 14:32:00",
  "workspace": "default"
}

{
  "id": "tsk_live_a3f21",
  "type": "audio-audit",
  "title": "TTS Quality Check - Batch 42",
  "status": "Completed",
  "priority": "express",
  "result": {
    "approved": true,
    "pacing_natural": true,
    "quality_score": 96.5
  },
  "created_at": "2026-06-09 14:32:00"
}

[
  {
    "id": "tsk_live_a3f21",
    "type": "audio-audit",
    "title": "TTS Quality Check",
    "status": "Completed",
    "priority": "express",
    "created_at": "2026-06-09 14:32:00"
  }
]

{
  "tasks_submitted_today": 12,
  "tasks_submitted_week": 87,
  "tasks_submitted_month": 342,
  "tasks_completed": 328,
  "avg_completion_time": 18.4,
  "quality_score": 96.2,
  "balance": 1847.50
}

Webhook Events

Webhooks are sent as POST requests with JSON payloads. Each request includes an HMAC signature in the X-Verified-Workflows-Signature header for verification.

Event Types

Webhook Payload

{
  "event": "task.completed",
  "task_id": "tsk_live_a3f21",
  "completed_at": "2026-06-09T14:35:00Z",
  "results": {
    "approved": true,
    "quality_score": 96.5
  }
}

Verifying Signatures

import hmac, hashlib

def verify_signature(payload_body, signature_header, secret):
    timestamp = signature_header.split(',')[0].split('=')[1]
    signature = signature_header.split(',')[1].split('=')[1]
    signed_payload = f"t={timestamp},{payload_body}".encode('utf-8')
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Error Codes

Error Response Format

{
  "type": "https://api.verifiedworkflows.com/errors/validation-failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request body schema validation failed: ...",
  "instance": "/v1/tasks"
}

Idempotency

Include an Idempotency-Key header to safely retry requests without creating duplicate tasks. Keys are valid for 24 hours.

Idempotency-Key: unique-request-id-12345

SDKs & Libraries

Official SDKs are available for popular languages:

• Python: pip install verifiedworkflows
• Node.js: npm install @verifiedworkflows/sdk
• Go: go get github.com/verifiedworkflows/go-sdk

Need help? Contact support or view the interactive API reference.