API Reference

Base URL: https://api.firsthandapi.com

Authentication

All requests require a Bearer token:

Authorization: Bearer fh_live_...

Key types:

• fh_live_* — Production keys (real jobs, real billing)
• fh_test_* — Sandbox keys (simulated submissions, no charges)

Request Format

• Content-Type: application/json
• All mutating POST endpoints require an Idempotency-Key header
• List endpoints support cursor-based pagination via cursor and limit parameters

Response Format

All responses follow a consistent envelope:

// Success (single resource)
{
  "object": "job",
  "id": "job_01JQ...",
  "status": "open",
  ...
}
 
// Success (list)
{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "..."
}
 
// Error
{
  "error": {
    "type": "validation_error",
    "message": "description is required",
    "request_id": "req_01JQ..."
  }
}

Rate Limits

Rate-limited responses return 429 with a Retry-After header.