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

# API Versioning

> Learn about Smartbills API versioning, backwards compatibility, and how to manage version changes

## Overview

The Smartbills API uses versioning to ensure backward compatibility and allow for improvements without breaking existing integrations. The version is specified in the URL path.

## Current Version

The current API version is **v1**.

All API requests should include the version in the URL:

```
https://api.smartbills.io/v1/expenses
```

## Version Format

API versions are specified in the URL path:

```
https://api.smartbills.io/{version}/{resource}
```

Examples:

```
https://api.smartbills.io/v1/expenses
https://api.smartbills.io/v1/expense-reports
https://api.smartbills.io/v1/businesses
https://api.smartbills.io/v1/vendors
```

<Warning>
  **Always specify the version**: Do not omit the version from the URL path. Requests without a version may return unexpected results.
</Warning>

## Checking Your API Version

You can check which version you are using by inspecting the response headers:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.smartbills.io/v1/expenses \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'x-tenant-id: 123' \
    --verbose 2>&1 | grep -i "x-api-version"
  ```

  ```javascript JavaScript theme={null}
  import { SmartbillsClient } from '@smartbills/sdk';

  const client = new SmartbillsClient({
    accessToken: 'YOUR_API_KEY',
    businessId: 123
  });

  // When making raw fetch requests:
  const response = await fetch('https://api.smartbills.io/v1/expenses', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-tenant-id': '123'
    }
  });

  console.log('API Version:', response.headers.get('X-API-Version')); // "v1"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.smartbills.io/v1/expenses',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'x-tenant-id': '123'
      }
  )

  print('API Version:', response.headers.get('X-API-Version'))  # "v1"
  ```
</CodeGroup>

## Backwards Compatibility Policy

We maintain backward compatibility within a major version. This means your integration will not break as long as you stay on the same major version.

### Non-Breaking Changes (Safe)

The following changes are considered non-breaking and may be made within a major version without notice:

* Adding new API endpoints
* Adding new optional request parameters
* Adding new properties to API responses
* Adding new webhook event types
* Adding new error codes
* Adding new enum values to existing fields
* Changing the order of properties in responses

<Tip>
  **Best practice**: Your code should ignore unknown fields in API responses to handle new properties added in the future.
</Tip>

### Breaking Changes (Require New Version)

The following changes are considered breaking and will only be introduced in a new major version:

* Removing or renaming API endpoints
* Removing or renaming required request parameters
* Removing or renaming response properties
* Changing the type of existing fields
* Changing authentication methods
* Changing error response formats
* Removing enum values from existing fields

## Deprecation Policy

When a new major version is released:

<Steps>
  <Step title="Deprecation Notice">
    We provide at least **12 months notice** before deprecating an old version. You will receive notifications via email and the developer portal.
  </Step>

  <Step title="Deprecation Period">
    The old version continues to work during the deprecation period. You will see deprecation warnings in response headers.
  </Step>

  <Step title="Migration Guides">
    Detailed migration guides are provided to help you upgrade to the new version.
  </Step>

  <Step title="End of Life">
    After the deprecation period, the old version stops receiving updates. API requests to the deprecated version may eventually return errors.
  </Step>
</Steps>

### Deprecation Headers

When a version is deprecated, responses include a warning header:

```http theme={null}
X-API-Deprecated: true
X-API-Sunset-Date: 2027-01-01
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always Specify the Version" icon="hashtag">
    Always include the version number in your API requests. Do not rely on default versions.

    ```
    # Correct
    https://api.smartbills.io/v1/expenses

    # Avoid
    https://api.smartbills.io/expenses
    ```
  </Accordion>

  <Accordion title="Handle Unknown Fields Gracefully" icon="question">
    Your code should ignore unknown fields in API responses to handle new properties added in the future without breaking.
  </Accordion>

  <Accordion title="Subscribe to API Updates" icon="bell">
    Subscribe to our developer newsletter and monitor the changelog to receive notifications about new versions, deprecation notices, and new features.
  </Accordion>

  <Accordion title="Test in Sandbox First" icon="flask">
    When migrating to a new API version, test thoroughly in the sandbox environment before updating production.
  </Accordion>
</AccordionGroup>

## Version History

### v1 (Current)

**Released:** January 2024

**Status:** Active

**Features:**

* Complete REST API for expenses, expense reports, businesses, vendors, and more
* OAuth2 and API key authentication
* Webhook support for real-time event notifications
* Comprehensive error handling with error codes
* Multi-language support (en-CA, fr-CA, en-US)
* Multi-tenant architecture with `x-tenant-id` header
* Pagination, sorting, and filtering on all list endpoints

## Related Resources

<CardGroup cols={2}>
  <Card title="API Introduction" icon="book" href="/api-reference/introduction">
    API overview and getting started
  </Card>

  <Card title="Environments" icon="server" href="/api-reference/environments">
    Sandbox and production environments
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/errors">
    Error codes and handling
  </Card>

  <Card title="Authentication" icon="shield" href="/api-reference/authentication">
    Authentication methods
  </Card>
</CardGroup>

## Getting Help

If you have questions about API versioning or need help migrating to a new version:

* **Email**: [developers@smartbills.io](mailto:developers@smartbills.io)
* **Developer Portal**: [developers.smartbills.io](https://developers.smartbills.io)
* **Documentation**: [docs.smartbills.io](https://docs.smartbills.io)