---
title: API versions
description: How the version header selects behaviour, how to pin a version, and how generations and etags guard a write.
type: reference
product: platform
summary: A date in the Sylphx-Version header, echoed back on every response.
updated: 2026-09-28
order: 7
---

The base URL is `https://api.sylphx.com/v1`. The `v1` in the path is the shape
of the API, and it never changes.

The version is a date, `YYYY-MM-DD`, carried in the `Sylphx-Version` request
header. A call that names a version gets the same header back with the version
that answered it, so the version a response was produced under is never a
guess.

<CodeBlock
	language="bash"
	code={`curl https://api.sylphx.com/v1/whoami \\
  -H "Authorization: Bearer $SYLPHX_API_KEY" \\
  -H "Sylphx-Version: YYYY-MM-DD"`}
/>

## How a version is chosen

The version is the first one found in this order:

1. The `Sylphx-Version` header on the call.
2. The version pinned on the key that made the call.
3. The version pinned on the organization.

Both pins are set when the key or the organization is created, so a version is
always resolved without you naming one.

## Today

There is no version stream yet. The version you request is the version you get
back, and no behaviour changes by version. This page is the contract for what
happens when that changes, not a list of versions to choose from.

## When a version changes

A breaking change ships as a new date. Every older version keeps working, so a
call that names one keeps its behaviour. A version is removed only after 90 days
with no traffic and 30 days of notice.

## Pinning a version

Pin the version on your organization when you want an upgrade to be a decision
rather than an event. The TypeScript SDK takes an `apiVersion` option, which
sends the header for you.

## Change detection

Every resource carries two fields for change detection, both in its `meta`:

- `generation`, which increases by one on every change to the resource's spec.
- `etag`, a strong etag for the current state of the resource, which changes on
  any change to the spec, the status or the metadata.

Send the `etag` back with a write to make the write fail rather than overwrite
someone else's change; the code that comes back is `ETAG_MISMATCH`, on
[Errors](/docs/platform/errors).

<RelatedDocs
	links={[
		{ href: '/docs/platform/errors', label: 'Errors' },
		{ href: '/docs/platform/keys-and-scopes', label: 'Keys and scopes' },
	]}
/>