> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Date-based API versioning lets you adopt breaking changes on your own schedule.

## Overview

The Arcus API is versioned by date. When a breaking change ships, a new version date is published and the previous version continues to work for at least **12 months**. This lets you adopt changes on your own schedule without emergency upgrades.

Non-breaking changes (new fields, new optional parameters, new endpoints, new enum values) are added to the current version without a new version date.

## Specifying a version

Pass the `Arcus-Version` header on every request:

```bash theme={null}
curl https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Arcus-Version: 2026-05-01"
```

If you omit the header, the API uses the version your API key was created on. This default ensures existing integrations do not break when new versions ship.

## Current version

The current stable version is `2026-05-01`. This is the version the initial API endpoints were published on.

## Version history

| Version      | Status  | End-of-life |
| ------------ | ------- | ----------- |
| `2026-05-01` | Current | Not set     |

## What counts as a breaking change

Arcus follows a strict definition of "breaking" to avoid unnecessary version bumps:

**Breaking (requires new version):**

* Removing a field from a response
* Changing a field's type (string -> integer, UUID -> slug)
* Changing HTTP status codes on success paths
* Removing an endpoint
* Changing required fields on a request body
* Changing filter parameter semantics

**Non-breaking (added to current version):**

* New optional request fields
* New response fields
* New endpoints
* New enum values (your code must handle unknown enum values gracefully)
* New optional headers
* New error codes on existing error types

## SDK version pinning

```javascript theme={null}
// Pin in package.json to control when you pick up new behavior
"@arcuserp/sdk-node": "^1.2.0"
```

SDKs are versioned independently from the API. SDK patch releases are always safe to apply. SDK minor releases may add new API version support. SDK major releases may drop support for deprecated API versions.

## Upgrading to a new version

1. Read the [changelog](/changelog) for the new version
2. Update the `Arcus-Version` header in your test environment
3. Run your integration tests
4. Fix any breaking changes in a dev/staging deploy
5. Update the header in production

The SDK's `arcusVersion` config option sets the header for all requests:

<CodeGroup>
  ```javascript Node theme={null}
  const arcus = new Arcus({
    apiKey: process.env.ARCUS_API_KEY,
    entityId: process.env.ARCUS_ENTITY_ID,
    arcusVersion: '2026-05-01',
  });
  ```

  ```python Python theme={null}
  arcus = Arcus(
      api_key=os.environ['ARCUS_API_KEY'],
      entity_id=os.environ['ARCUS_ENTITY_ID'],
      arcus_version='2026-05-01',
  )
  ```

  ```go Go theme={null}
  client := arcus.NewClient(
      os.Getenv("ARCUS_API_KEY"),
      arcus.WithEntityID(os.Getenv("ARCUS_ENTITY_ID")),
      arcus.WithAPIVersion("2026-05-01"),
  )
  ```
</CodeGroup>