---
title: "API versioning and deprecation policy"
description: "How the Primitive REST API is versioned, which changes a client should be ready for, and how deprecated operations and fields are marked."
canonical: "https://docs.primitive.dev/docs/versioning"
last-updated: "2026-05-17T00:00:00.000Z"
---

# Primitive API versioning and deprecation policy

The Primitive REST API uses URL path versioning. The current version is **v1**, served at `https://api.primitive.dev/v1`.


```
curl https://api.primitive.dev/v1/account \
  -H "Authorization: Bearer $PRIMITIVE_AUTH_TOKEN"
```


## Changes

Changes to the API are listed in the changelog. Operations, request fields, response fields, enum values and error codes are added to v1 without a version change, so a client should:

- Ignore response fields it does not recognize.

- Treat an `error.code` it does not recognize as a generic error rather than crash.

- Accept enum values it does not recognize in fields whose schema does not say `additionalValues: false`.

## Deprecation policy

A deprecated operation or field is marked like this:

- In the OpenAPI document: the operation or field is marked `deprecated: true`, with a `description` naming the replacement.

- In responses: a request that uses it still works while it is deprecated, and its response carries a `Deprecation` header per RFC 9745 (the date it was deprecated, as `@<unix seconds>`) and `Link: <https://docs.primitive.dev/docs/versioning>; rel="deprecation"`. Once a removal date is scheduled the response also carries a `Sunset` header per RFC 8594 with that date. For a deprecated request-body field, the headers are sent on responses to requests that include the field, once the body has been read (a `401` or `429` answered before that does not carry them).

There are no scheduled removals in v1 today. One field is deprecated without a removal date: `outbound` on `POST /v1/domains` is accepted and ignored, because outbound DNS is provisioned for every new domain claim. Requests that send it receive the `Deprecation` and `Link` headers.

## How agents should declare a target version

The bearer-authenticated v1 surface does not require an `Accept: application/vnd.primitive.v1+json` header today; the URL path is the version selector. If you want a defensive header anyway, send:


```
Accept: application/json, application/vnd.primitive.v1+json
```


The API ignores unknown vendor types in the Accept header.

## OpenAPI spec versioning

The OpenAPI document is served at `https://api.primitive.dev/v1/openapi` (also as `/openapi.json` and `/openapi.yaml`) and carries an `info.version` field. That number tracks the document's editorial revisions (added descriptions, doc-only changes, augmented examples), not the API version, which is the `/v1` path prefix.

Maintained by the [primitive.dev team](/about) · [Trust & security](/trust)Last updated: May 17, 2026