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

# API Versioning

> How Credence versions its API, following the same principles as Discord's API versioning strategy.

Credence versions its API to allow changes without breaking existing integrations. Each version is stable — once released, breaking changes are only introduced in new versions.

## Specifying a version

Include the API version in the request path:

```http theme={null}
https://api.credencework.com/v1/resource
```

If no version is specified, requests default to the current stable version. Relying on the default is discouraged for production integrations.

## API versions

| Version | Status    | Default |
| ------- | --------- | ------- |
| 2       | Available |         |
| 1       | Available | ✓       |

<Note>
  Deprecated versions continue to function but no longer receive new features. Discontinued versions return an error.
</Note>

## Version lifecycle

Each API version moves through the following stages:

<Steps>
  <Step title="Available">
    The version is stable and recommended for production use.
  </Step>

  <Step title="Deprecated">
    The version still works but is no longer recommended. Plan to migrate.
  </Step>

  <Step title="Discontinued">
    The version is removed. Requests will fail.
  </Step>
</Steps>

## Breaking vs. non-breaking changes

The following changes are considered **non-breaking** and can occur within an existing version:

* Adding new API endpoints
* Adding new optional request parameters
* Adding new fields to responses
* Adding new event types
* Changing the order of fields in responses
* Changing the length or format of opaque identifiers

The following are **breaking** and require a new version:

* Removing or renaming endpoints, fields, or parameters
* Changing the type of an existing field
* Changing authentication or permission requirements for existing endpoints
* Changing existing error codes or status codes

## Handling version changes

* Pin your integration to a specific version in the request URL.
* Subscribe to changelog updates to track deprecations.
* Ignore unknown fields in API responses so additive changes don't break your client.
* Test against the newest version before migrating production traffic.