primitive docs
primitive app

API Versioning

The Primitive REST API uses URL path versioning. The current and only supported major version is v1, served at https://api.primitive.dev/v1.

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

What's covered by the v1 contract

Within the v1 surface, these are considered part of the contract and changes to them require a new major version:

  • The set of operation paths, HTTP methods, and operation IDs published in the OpenAPI spec at /openapi.yaml.
  • The shape of request bodies (required fields, types, accepted enum values).
  • The shape of response bodies (field names, types, presence guarantees).
  • The error envelope: { success, error: { code, message, request_id, details? } } and the set of error.code values documented at Errors.
  • Auth model: bearer token in Authorization header, prefixes (prim_, prim_oat_), 401 challenge shape (WWW-Authenticate: Bearer realm="Primitive API", resource_metadata="...").
  • Webhook delivery contract: Primitive-Signature header, HMAC-SHA256 signing scheme, signed-string format (${timestamp}.${rawBody}).

What's allowed without a new major version

These are explicitly NOT breaking changes:

  • Adding new operations.
  • Adding new optional request fields.
  • Adding new response fields (clients must tolerate unknown fields).
  • Adding new error.code values for new failure modes (clients must treat unrecognized codes as a generic error and not crash).
  • Adding new enum values to fields whose schema does not say additionalValues: false.
  • Tightening server-side validation that was previously lax (e.g., adding a length cap to a string field that previously had none). Clients that send values within previously-documented limits are unaffected.

Deprecation policy

When a v1 operation, field, or behavior is on a path to removal:

  1. Announcement: the operation or field is marked deprecated: true in the OpenAPI spec, with a description calling out the replacement.
  2. Soft warning: deprecated requests continue to work and additionally receive a Sunset response header per RFC 8594, indicating the planned removal date.
  3. Minimum sunset window: at least 90 days between announcement and removal. Removal lands in v2, never in v1.

There are no scheduled deprecations in v1 today.

What constitutes v2

If we ship a v2 surface, it will:

  • Live at https://api.primitive.dev/v2 (new path prefix; v1 continues to serve at /v1 until its own sunset).
  • Be announced at least 90 days before v1 is sunset, with the v1 sunset date published in the OpenAPI spec via info.x-sunset-date and on the status page.
  • Ship with an SDK + CLI release tagged for the v2 surface, plus a migration guide linking field-by-field.

There is no scheduled v2 release.

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 shipped spec at https://www.primitive.dev/openapi.yaml carries an info.version field. That number tracks the spec's editorial revisions (added descriptions, doc-only changes, augmented examples), not the API contract. The contract version is fixed at v1 until/unless a v2 ships.