Versioning

The short version

• The API version is the /v1 in the path.
• Finn accepts a Finn-Version header, but ignores it today.
• Every response is the current v1 shape, whatever header you send.
• The changelog lists every change, with its date.
• Version pinning will come with the next breaking change.

The Finn-Version header

You can send a date in Finn-Version, for example 2026-11-01:

curl https://api.hirefinn.ai/api/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Finn-Version: 2026-11-01"

Finn accepts the header and does nothing with it. It does not check the value. It does not echo it back. A missing header, an old date and a future date all get the same response: the current one.

Sending it now is harmless. It does not lock your client to anything yet.

What counts as a change

New endpoints, new optional fields, new response fields, new enum values and new webhook events can ship in v1 at any time. They are not breaking. Write clients that ignore fields they don't know, and treat status values as open lists. See conventions.

The full list of what counts as breaking is in the changelog. So far, each breaking change was announced there with a date, and then applied to every client.

When pinning arrives

Pinning will turn on with the next breaking change. Then:

• The change is announced in the changelog before it ships, with its date.
• A request with a Finn-Version before that date keeps the old shape.
• The date you send is the version you get.

Until then there is nothing to pin. Read the changelog to see what changed and when.

Experimental and rolling-out endpoints

Endpoints marked experimental (such as Sales) or rolling out are outside this promise. They can change shape before they are marked stable. The page that documents them says so at the top.