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

# Versioning

> How X API versioning works, the difference between v1.1, v2, and enterprise, and which changes are considered breaking versus additive updates.

The X API uses version numbers in endpoint paths to provide stability while allowing for evolution. Understanding our versioning strategy helps you plan integrations and stay current.

***

## Current versions

| Version        | Status    | Description                                          |
| :------------- | :-------- | :--------------------------------------------------- |
| **v2**         | Current   | Modern endpoints, flexible pricing, all new features |
| **v1.1**       | Legacy    | Limited support, minimal updates                     |
| **Enterprise** | Available | High-volume access with dedicated support            |

<Tip>
  Use **X API v2** for all new projects. This is where all new features ship.
</Tip>

***

## Version in URLs

The version number appears in the endpoint path:

```
https://api.x.com/2/tweets
                   ^
                   version
```

***

## Breaking vs. non-breaking changes

### Breaking changes (require code updates)

These changes only occur in major version bumps:

* Removing an endpoint
* Removing a response field
* Removing a query parameter
* Adding a new required parameter
* Changing a field's data type
* Renaming a field or resource
* Changing response codes or error types
* Modifying authorization scopes

### Non-breaking changes (additive)

These can happen at any time without version changes:

* Adding a new endpoint
* Adding a new optional parameter
* Adding a new response field
* Adding new OAuth scopes
* Changing error message text
* Nulling fields for privacy/security reasons

***

## Release schedule

| Type                     | Frequency             | Notice                            |
| :----------------------- | :-------------------- | :-------------------------------- |
| **Major versions**       | No more than annually | Migration guides provided         |
| **Non-breaking changes** | Ongoing               | Changelog updates                 |
| **Security patches**     | As needed             | May be applied to current version |

***

## Deprecation policy

When we release a new major version:

1. **Deprecation**: Previous version is marked deprecated
2. **Support period**: Deprecated version continues to work for a defined period
3. **Retirement**: Deprecated version is removed

### Definitions

| Status         | Meaning                                              |
| :------------- | :--------------------------------------------------- |
| **Active**     | Fully supported with new features and fixes          |
| **Deprecated** | No new features; critical bugs only; use discouraged |
| **Retired**    | No longer accessible                                 |

***

## Staying informed

Get notified about changes:

<CardGroup cols={2}>
  <Card title="Changelog" icon="clock-rotate-left" href="/changelog">
    All platform changes and updates.
  </Card>

  <Card title="Forum Announcements" icon="bullhorn" href="https://devcommunity.x.com/c/announcements/22">
    Breaking change notices.
  </Card>

  <Card title="@XDevelopers" icon="x-twitter" href="https://x.com/XDevelopers">
    Platform news and updates.
  </Card>

  <Card title="Newsletter" icon="envelope" href="/newsletter">
    Monthly digest.
  </Card>
</CardGroup>

***

## Migration resources

When a new version is released, we provide:

* **Migration guides**: Step-by-step upgrade instructions
* **Endpoint mapping**: v1 to v2 equivalents
* **Data format changes**: Object model differences

<CardGroup cols={2}>
  <Card title="Migration overview" icon="route" href="/x-api/migrate/overview">
    Current migration guidance.
  </Card>

  <Card title="Endpoint map" icon="map" href="/x-api/migrate/x-api-endpoint-map">
    v1 to v2 endpoint mapping.
  </Card>
</CardGroup>

***

## Best practices

<CardGroup cols={2}>
  <Card title="Use v2" icon="arrow-up">
    Start new projects on the latest version.
  </Card>

  <Card title="Monitor announcements" icon="bell">
    Subscribe to changelog and forum updates.
  </Card>

  <Card title="Test changes" icon="flask">
    Test in development before production updates.
  </Card>

  <Card title="Plan migrations" icon="calendar">
    Don't wait until deprecation to upgrade.
  </Card>
</CardGroup>