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

# Versioning

> Understanding Lightyshare API versioning strategy

Lightyshare uses a date-based versioning system inspired by Stripe's approach, ensuring backward compatibility while continuously improving the API.

## Version Format

API versions follow the **YYYY-MM-DD** format:

```
2025-08-16
```

This format makes it immediately clear when a version was released and helps track API evolution over time.

## How Versioning Works

<Steps>
  <Step title="Token-based Default">
    When you create an API token, it's automatically tied to the latest API version available at that time
  </Step>

  <Step title="Stable by Default">
    Your token continues using its original version even as new versions are released
  </Step>

  <Step title="Optional Override">
    You can override the version for specific requests using the `lighty-version` header
  </Step>
</Steps>

## Using API Versions

### Default Version (Token-based)

Your token uses its default version automatically:

```bash theme={null}
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_live_abc123..."
```

### Override Version (Per Request)

Use a different version for a specific request:

```bash theme={null}
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_live_abc123..." \
  -H "lighty-version: 2025-01-15"
```

### Check Current Version

The API version used is always returned in the response header:

```
X-API-Version: 2025-08-16
```

## Version Compatibility

<CardGroup cols={2}>
  <Card title="Backward Compatible" icon="check">
    Existing endpoints continue working as expected
  </Card>

  <Card title="Non-Breaking Changes" icon="plus">
    New fields and endpoints don't affect existing integrations
  </Card>

  <Card title="Deprecation Notices" icon="triangle-exclamation">
    Advance warning before removing features
  </Card>

  <Card title="Migration Guides" icon="book">
    Documentation for upgrading between versions
  </Card>
</CardGroup>

## Types of Changes

### Non-Breaking Changes (No Version Update)

These changes don't require a new version:

* ✅ Adding new endpoints
* ✅ Adding optional request parameters
* ✅ Adding new response fields
* ✅ Adding new webhook events
* ✅ Performance improvements

### Breaking Changes (New Version Required)

These changes trigger a new version:

* ❌ Removing endpoints
* ❌ Removing or renaming fields
* ❌ Changing field types
* ❌ Modifying validation rules
* ❌ Changing authentication methods

## Version Lifecycle

```mermaid theme={null}
graph LR
    A[New Version Released] --> B[Available for Testing]
    B --> C[Set as Default for New Tokens]
    C --> D[Previous Version Supported]
    D --> E[Deprecation Notice]
    E --> F[End of Life]
```

### Support Timeline

| Stage          | Duration  | Description                               |
| -------------- | --------- | ----------------------------------------- |
| **Active**     | Ongoing   | Current default version for new tokens    |
| **Supported**  | 12 months | Previous versions remain fully functional |
| **Deprecated** | 6 months  | Warning period before removal             |
| **Sunset**     | -         | Version no longer available               |

## Best Practices

<Tabs>
  <Tab title="Development">
    ```bash theme={null}
    # Test with specific version during development
    export API_VERSION="2025-08-16"

    curl -X GET https://lightyshare.com/api/token-secured/product/123 \
      -H "Authorization: Bearer $API_KEY" \
      -H "lighty-version: $API_VERSION"
    ```
  </Tab>

  <Tab title="Production">
    ```javascript theme={null}
    // Lock version in production code
    const LIGHTYSHARE_API_VERSION = '2025-08-16';

    fetch('https://lightyshare.com/api/token-secured/product/123', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'lighty-version': LIGHTYSHARE_API_VERSION
      }
    });
    ```
  </Tab>
</Tabs>

## Version History

<Note>
  Check the [Changelog](/changelog) for detailed information about each version.
</Note>

### Current Version: 2025-08-16

* Initial stable release
* Full product, bundle, and rental management
* Token-based authentication

## Migration Guide

When upgrading to a new version:

1. **Review the changelog** for breaking changes
2. **Test in development** with the new version header
3. **Update your code** to handle any changes
4. **Deploy gradually** using version headers
5. **Update your token** when ready

## Version Testing

Test how your integration works with different versions:

```bash theme={null}
# Test with current version
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_test_..." \
  -H "lighty-version: 2025-08-16"

# Test with future version (if available)
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_test_..." \
  -H "lighty-version: 2025-09-01"
```

## FAQ

<AccordionGroup>
  <Accordion title="What happens if I don't specify a version?">
    Your API token's default version is used automatically. This is the version that was current when your token was created.
  </Accordion>

  <Accordion title="Can I change my token's default version?">
    No, but you can create a new token which will use the latest version, or override the version per request using headers.
  </Accordion>

  <Accordion title="How do I know which version I'm using?">
    Check the `X-API-Version` header in any API response to see which version was used for that request.
  </Accordion>

  <Accordion title="Will my integration break when new versions are released?">
    No, your token continues using its original version. New versions don't affect existing integrations unless you explicitly upgrade.
  </Accordion>
</AccordionGroup>

Next: View the [Changelog](/changelog) →