FirstHandAPI Documentation

Crowdsourced content collection via API. Post jobs requesting files, workers deliver, AI scores quality.

What is FirstHandAPI?

FirstHandAPI is an API-first marketplace that turns crowdsourced file collection into infrastructure. Buyers post jobs requesting images, audio, or video from a distributed pool of mobile workers. Every submission is automatically scored for quality by a multi-model AI ensemble. Approved files are delivered to a per-job folder and accessible via API.

How it works

1. Post a Job — Call POST /v1/jobs with description, file count, accepted formats, and price per file
2. Workers Accept — Workers on the FirstHandAPI iOS app browse and accept jobs
3. Upload Files — Workers upload photos, audio, or video from their phone
4. AI Scores, Labels & Delivers — AI rates each file 1-5 stars and auto-generates structured annotations (object labels, OCR, scene classification, and more). Files scoring 3+ are auto-approved and delivered to your folder

Quick Links

• Quickstart Guide — Post your first job in 5 minutes
• API Reference — Complete endpoint documentation
• TypeScript SDK — @firsthandapi/sdk
• Python SDK — firsthandapi

Use Cases

• User-Generated Content (UGC) — Collect authentic photos, videos, and audio from real people for brands, marketplaces, and social platforms
• Ground Truth & Validation Data — Gather real-world images, audio, and video to validate ML model predictions and measure accuracy
• LLM Training Data — Source diverse multimodal data for foundation model training and fine-tuning

Key Features

• AI Quality Gate — Every submission scored 1-5 stars automatically
• Folder Delivery — Approved files land in your per-job S3 folder
• Per-File Pricing — You set the price. Workers get 80%, platform takes 20%
• Webhook Notifications — submission.approved and job.completed events
• MCP Server — AI agents can post jobs and retrieve files directly
• Auto-Labeling & Annotations — Every file gets structured metadata: object labels, OCR, scene classification, color palettes, speaker counts, transcripts (guide)
• Anti-Fraud Screening — Reverse image search, EXIF validation, and AI-generated content detection