GuidesVersioning

Versioning & Deprecation

Current Version

All endpoints are under /v1/:

https://api.firsthandapi.com/v1/jobs
https://api.firsthandapi.com/v1/billing/balance

Backward Compatibility

We follow a strict backward compatibility policy within a major version:

We will NOT:

  • Remove or rename existing fields from responses
  • Change the type of existing fields
  • Remove or rename endpoints
  • Change the meaning of status codes
  • Make optional parameters required

We MAY:

  • Add new optional fields to responses
  • Add new optional query parameters
  • Add new endpoints
  • Add new webhook event types
  • Add new error types

Your integration will not break from additive changes. Always ignore unknown fields in responses to be forward-compatible.

Breaking Change Policy

When a breaking change is necessary:

  1. 6-month notice — announced via email, changelog, and API response headers
  2. Sunset header — Sunset: Sat, 01 Mar 2027 00:00:00 GMT added to affected endpoints
  3. New version released — e.g., /v2/jobs becomes available alongside /v1/jobs
  4. Migration guide published — step-by-step instructions for upgrading
  5. Old version sunset — after the notice period, the old version returns 410 Gone

Response to Deprecated Endpoints

When calling a deprecated (but still active) endpoint:

HTTP/1.1 200 OK
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Deprecation: true
Link: <https://docs.firsthandapi.com/migration/v2>; rel="successor-version"

The response still works, but the headers warn you to migrate.

Best Practices

  • Pin to /v1/ — always include the version in your URLs
  • Ignore unknown fields — don’t fail on new fields in responses
  • Subscribe to the changelog — stay informed about upcoming changes
  • Test with sandbox after updates — verify your integration still works
  • Monitor Sunset headers in production — alert when deprecation warnings appear
Data Types & FormatsWorker Platform