Quick Reference
Every FirstHandAPI endpoint in one table. All requests require Authorization: Bearer <api_key> unless noted.
Base URL: https://api.firsthandapi.com
Buyer API (/v1/)
| Method | Path | Description | Scope |
|---|---|---|---|
POST | /v1/auth/signup | Create org + API key + $2.50 credits | None |
POST | /v1/jobs | Create content collection job (escrows credits) | jobs:write |
GET | /v1/jobs | List jobs (cursor pagination) | jobs:read |
GET | /v1/jobs/:id | Get job detail (supports long-poll via Prefer: wait=N) | jobs:read |
POST | /v1/jobs/:id/cancel | Cancel job, refund remaining credits | jobs:write |
POST | /v1/jobs/:id/rate | Rate completed job (1-5 stars) | jobs:write |
GET | /v1/jobs/:id/files | List approved files with S3 download URLs | jobs:read |
GET | /v1/jobs/:id/submissions | List submissions with AI scores | jobs:read |
POST | /v1/api_keys | Create API key | keys:manage |
GET | /v1/api_keys | List API keys | keys:manage |
POST | /v1/api_keys/:id/rotate | Rotate key (24h overlap) | keys:manage |
POST | /v1/api_keys/:id/revoke | Revoke key immediately | keys:manage |
POST | /v1/webhook_endpoints | Create webhook endpoint | webhooks:write |
GET | /v1/webhook_endpoints | List webhook endpoints | webhooks:read |
GET | /v1/webhook_endpoints/:id | Get endpoint detail | webhooks:read |
PATCH | /v1/webhook_endpoints/:id | Update endpoint | webhooks:write |
DELETE | /v1/webhook_endpoints/:id | Delete endpoint | webhooks:write |
POST | /v1/webhook_endpoints/:id/rotate_secret | Rotate signing secret | webhooks:write |
GET | /v1/webhook_events | List webhook events | webhooks:read |
POST | /v1/webhook_events/:id/replay | Replay failed event | webhooks:write |
GET | /v1/billing/credits | Get credit balance | usage:read |
GET | /v1/billing/transactions | List credit transactions | usage:read |
POST | /v1/billing/credits/purchase | Purchase credits (Stripe) | billing:write |
GET | /v1/organization/settings | Get org settings | Any |
PATCH | /v1/organization/settings | Update org settings | Any |
Worker API (/internal/worker/)
| Method | Path | Description | Auth |
|---|---|---|---|
GET | /internal/worker/jobs/available | Browse open jobs (priority window) | Worker token |
POST | /internal/worker/jobs/:id/accept | Accept a job | Worker token |
POST | /internal/worker/jobs/:id/withdraw | Withdraw from job | Worker token |
POST | /internal/worker/jobs/:id/flag | Flag job as unreasonable | Worker token |
POST | /internal/worker/submissions/:id/upload | Upload file (multipart) | Worker token |
POST | /internal/worker/submissions/:id/retry | Retry rejected submission | Worker token |
GET | /internal/worker/submissions/:id | Get submission (poll for score) | Worker token |
GET | /internal/worker/submissions | Submission history | Worker token |
Common Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <fh_live_...> or Bearer <fh_test_...> |
Idempotency-Key | On POST | Unique key for safe retries |
Prefer | Optional | wait=N for long-poll (max 60s) on GET /v1/jobs/:id |
Webhook Event Types
| Event | Trigger |
|---|---|
submission.approved | File scored 3+ stars, approved |
submission.rejected | File scored below threshold |
job.completed | All requested files collected |
job.cancelled | Job cancelled by buyer |