# HumanDispatch

> The API for real-world marketing execution. AI agents can request structured outcomes — product shoots, UGC creation, event coverage, retail audits — through clean API endpoints. Vetted humans execute, automated QA verifies, escrowed payments release on acceptance.

## API

Base URL: https://api.humandispatch.io
Auth: Bearer token in Authorization header
Content-Type: application/json

## Quick Start

1. GET /v1/templates — list available task templates with JSON schemas
2. POST /v1/tasks — create a task by filling a template schema
3. POST /v1/tasks/{id}/quote_requests — request quotes from talent
4. POST /v1/quotes/{id}/accept — accept a quote
5. POST /v1/bookings — create booking with escrow hold
6. POST /v1/work_orders/{id}/deliverables — talent uploads deliverables
7. GET /v1/work_orders/{id}/qa — run automated QA checks
8. POST /v1/work_orders/{id}/accept — accept work and release payout

## MCP Server

HumanDispatch ships an MCP (Model Context Protocol) server with 13 tools:
get_templates, get_template, search_talent, create_task, request_quotes,
get_quotes, accept_quote, create_booking, get_booking, submit_checkin,
register_deliverables, get_qa, request_changes, accept_work

Connect via stdio: HUMANDISPATCH_API_URL=https://api.humandispatch.io HUMANDISPATCH_API_KEY=sk_live_... bun run src/mcp/server.ts

## Templates

### PRODUCT_PHOTO_ECOMM
Product photography for e-commerce. White/lifestyle backgrounds, multiple angles, retouched.
task_spec: { product_count: int, background: enum[white|lifestyle|flat_lay|contextual], angles: string[], retouch_level: enum[none|light|full] }
Risk: low | Onsite: yes

### UGC_VERTICAL_BATCH
Batch of UGC-style vertical video clips with hooks and talking points.
task_spec: { clip_count: int(3-20), hook_prompts: string[], talking_points: string[], claims_blocklist: string[], captions_required: bool }
Risk: medium | Onsite: no

### EVENT_PHOTO_COVERAGE
On-site event photography with edited selects.
task_spec: { min_edits: int(20+), shot_list: string[], edit_style: enum[clean_natural|cinematic|bright_airy|moody|brand_match], raw_delivery: bool }
Risk: low | Onsite: yes

### EVENT_HIGHLIGHT_VIDEO
Capture event footage and produce 30-90s highlight reel.
task_spec: { target_length_sec: int(30-120), aspect_ratios: enum[9:16|16:9|1:1|4:5][], audio_policy: enum[licensed_or_original|original_only|no_music|client_provides], broll_minutes: int }
Risk: low | Onsite: yes

### ON_SITE_STORY_PACK
On-site IG/TikTok story pack with same-day turnaround.
task_spec: { story_count: int(3-20), turnaround_hours: int(2-24), cta_text: string }
Risk: low | Onsite: yes

### RETAIL_AUDIT_PHOTO_CHECK
In-store audit with GPS-verified shelf/signage/POS photos.
task_spec: { checklist: enum[shelf|POS|endcap|window|signage|cooler|floor_display][], required_angles: enum[wide|closeup|detail|context][], notes_required: bool, store_meta: { chain, store_id, department } }
Risk: medium | Onsite: yes

### OOH_ASSET_VERIFICATION
Verify OOH/billboard placement with GPS-timestamped photos.
task_spec: { asset_id: string, required_text: string, time_windows: datetime[] }
Risk: low | Onsite: yes

### STREET_TEAM_DISTRIBUTION
Flyer/sample distribution in GPS-fenced zones.
task_spec: { quantity: int(50-5000), allowed_zones: { lat, lng, radius_m }[], do_not_target: string[], script: string }
Risk: high | Onsite: yes

### POPUP_EVENT_STAFFING
Brand ambassador staffing with shift checkpoints.
task_spec: { role: enum[brand_ambassador|demo_specialist|greeter|product_specialist|event_coordinator], dress_code: string, shift_checkpoints: enum[setup|midshift|close|hourly][] }
Risk: medium | Onsite: yes

### PODCAST_ON_SITE_CAPTURE
On-location multi-track audio recording.
task_spec: { format: enum[wav_48k|wav_44k|mp3_320|flac], tracks: string[], backup_recording: bool, mic_required: bool }
Risk: low | Onsite: yes

## Common Task Fields (required)

task_type: string — template ID
title: string(8-120)
location: { mode: enum[onsite|remote|hybrid], address?: string }
schedule: { start_at: datetime, duration_hours?: number, timezone?: string }
budget: { currency: enum[CAD|USD], pricing_model: enum[fixed|hourly], max_total: int(50-500000) }
deliverables: [{ kind: enum[photo|video|audio|text], count: int, format?: string, due_at?: datetime }]
task_spec: object — template-specific fields (see above)

## Error Codes

SCHEMA_VALIDATION_FAILED (400), POLICY_BLOCKED (403), AUTH_SCOPE_DENIED (403),
RATE_LIMITED (429), INSUFFICIENT_FUNDS (402), ESCROW_REQUIRED (402),
CONFLICT_IDEMPOTENCY (409), NOT_FOUND (404), INTERNAL (500)

## Rate Limits

General: 60 RPM (burst 120)
Money endpoints (booking/accept/resolve): 10 RPM (burst 20)
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

## Webhooks

Events: task.created, task.policy_blocked, quote.received, booking.confirmed,
booking.checkin_recorded, deliverable.registered, qa.completed,
work_order.accepted, payout.initiated, dispute.opened

POST /v1/webhooks to register. Signed with HMAC-SHA256.

## SDKs

TypeScript: npm install @humandispatch/sdk
Python: pip install humandispatch (coming soon)

## Links

- API: https://api.humandispatch.io
- Docs: https://docs.humandispatch.io
- GitHub: https://github.com/jdubb118/humandispatch
- MCP Server: https://github.com/jdubb118/humandispatch/tree/main/src/mcp