Skip to main content

API reference

Move to api.hirefinn.ai

Old API hosts stop on 1 June 2027: path mapping, auth headers and a checklist.

What is changing

The Finn API has one address: https://api.hirefinn.ai/v1. The older ways in, through the web app's host (https://www.hirefinn.ai/api/v1/...) or any other host, still work today but are deprecated.

Old hosts stop answering on Tuesday 1 June 2027 (00:00 UTC). After that date a request to an old host will no longer reach the API. Move every integration before then.

Nothing else about the API changes: the same endpoints, request bodies, responses, scopes, rate limits and API keys work on the new address.

How to tell if you're affected

Since 6 November 2026, every answer from an old host carries three headers:

Deprecation: true
Sunset: Tue, 01 Jun 2027 00:00:00 GMT
Link: <https://api.hirefinn.ai/v1>; rel="successor-version"

An answer from api.hirefinn.ai has none of them. If your logs or HTTP client show a Sunset header on a Finn response, that integration still uses an old host.

Organization admins also see a banner in the Finn dashboard naming the API keys, MCP keys and apps that called an old host in the last 30 days.

Path mapping

Replace the scheme, host and /api prefix. The rest of the path, the query string and the body stay the same.

OldNew
https://www.hirefinn.ai/api/v1/<path>https://api.hirefinn.ai/v1/<path>
https://<any other host>/api/v1/<path>https://api.hirefinn.ai/v1/<path>
https://www.hirefinn.ai/api/v1/chat/<path>https://api.hirefinn.ai/v1/chat/<path>
https://www.hirefinn.ai/api/v1/openapi.jsonhttps://api.hirefinn.ai/openapi.json
https://api.hirefinn.ai/api/v1/<path>Already on the new host. Works and has no sunset; https://api.hirefinn.ai/v1/<path> is the shorter form.

For example:

# Before
curl https://www.hirefinn.ai/api/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY"

# After
curl https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY"

The official SDKs already call https://api.hirefinn.ai/v1. If you passed them a custom base URL, remove it or set it to https://api.hirefinn.ai/v1.

Authentication headers

Your keys keep working on the new host; you don't need new ones. Check these while you move:

BeforeOn api.hirefinn.ai
Authorization: Bearer finn_live_... (org API key)Unchanged.
Authorization: Bearer finn_mcp_... or finn_oat_... (member token)Unchanged. If the member can act in more than one organization, send the Finn-Org: <organization id> header rather than naming the organization in the query or body.
A dashboard session cookie or session tokenNot accepted on the API (401 api_key_required). Create an API key instead.
A custom Host or X-Forwarded-Host headerRemove it. Call api.hirefinn.ai directly.
Calls from browser codeNot supported on either host. Call the API from your server.

See Authentication for key formats, expiry and rotation.

Checklist

  1. Search your code and configuration for hirefinn.ai/api/v1 and for any Finn host other than api.hirefinn.ai.
  2. Change the base URL to https://api.hirefinn.ai/v1 and redeploy.
  3. Allow outbound HTTPS to api.hirefinn.ai if your network uses an allow list.
  4. Make a test request and check that the answer has no Sunset header.
  5. Watch the dashboard banner: a key drops off the list once it hasn't called an old host for 30 days.

Timeline

DateWhat happens
6 November 2026Old hosts start sending Deprecation, Sunset and Link headers.
Now until 31 May 2027Old hosts keep working. Organization admins see which keys still use them.
1 June 2027Old hosts stop answering API requests. Only https://api.hirefinn.ai/v1 works.

Questions about the move: Support.