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

# Versioning

> Understanding Prisme.ai API versioning and compatibility

Prisme.ai follows a structured approach to API versioning to ensure backward compatibility while enabling evolution of the platform. This guide explains our versioning strategy, how to specify API versions, and our commitment to compatibility.

## Versioning Strategy

<CardGroup cols="2">
  <Card title="URL-Based Versioning" icon="link">
    Prisme.ai uses URL path-based versioning:

    ```
    https://api.studio.prisme.ai/v2/workspaces
    ```

    The version identifier (e.g., `v2`) is included in the URL path.
  </Card>

  <Card title="Major Versions" icon="code-branch">
    New major versions (v1, v2, v3) are released when:

    * Introducing breaking changes
    * Significantly restructuring resources
    * Changing fundamental behavior
  </Card>

  <Card title="Minor Updates" icon="code-commit">
    Updates within a version (v2.1, v2.2) for:

    * Adding new endpoints
    * Extending existing endpoints
    * Bug fixes and improvements
  </Card>

  <Card title="Version Lifecycle" icon="hourglass-half">
    Each major version undergoes these phases:

    * Beta: Early access, may change without notice
    * Stable: Full support, backward compatible
    * Deprecated: Still works but will be removed
    * Retired: No longer available
  </Card>
</CardGroup>

## Current API Versions

<Tabs>
  <Tab title="v2 (Current)">
    Version 2 is the current stable API version.

    <CardGroup cols="2">
      <Card title="Status" icon="circle-check">
        Stable and fully supported
      </Card>

      <Card title="Base URL" icon="link">
        `https://api.studio.prisme.ai/v2/`
      </Card>

      <Card title="Documentation" icon="book">
        This documentation describes the v2 API
      </Card>

      <Card title="Retirement Date" icon="calendar">
        No planned retirement date
      </Card>
    </CardGroup>

    **Key Features:**

    * Comprehensive workspace management
    * Document and knowledge base operations
    * Agent creation and management
    * Enhanced automation capabilities
    * Fine-grained permissions system
  </Tab>

  <Tab title="v1 (Deprecated)">
    Version 1 is deprecated but still supported.

    <CardGroup cols="2">
      <Card title="Status" icon="triangle-exclamation">
        Deprecated
      </Card>

      <Card title="Base URL" icon="link">
        `https://api.studio.prisme.ai/v1/`
      </Card>

      <Card title="Documentation" icon="book">
        Archive documentation available
      </Card>

      <Card title="Retirement Date" icon="calendar">
        December 31, 2025
      </Card>
    </CardGroup>

    <Warning>
      The v1 API is deprecated and will be retired on December 31, 2025. We recommend migrating to the v2 API as soon as possible.
    </Warning>
  </Tab>
</Tabs>

## Version Compatibility

<Accordion title="Backward Compatibility Policy">
  Within a major version, Prisme.ai commits to backward compatibility:

  **We Will Never:**

  * Remove endpoints or fields
  * Change the meaning of existing fields
  * Add required parameters
  * Change error codes in a way that breaks existing error handling

  **We May:**

  * Add new endpoints
  * Add optional fields to responses
  * Add optional parameters to requests
  * Extend enum values
  * Fix bugs that don't change intended behavior

  <Warning>
    Beta versions do not follow the backward compatibility guarantee and may change without notice.
  </Warning>
</Accordion>

<Accordion title="Breaking Changes">
  Breaking changes are only introduced in new major versions. Examples of breaking changes include:

  * Removing or renaming fields in responses
  * Changing data types of existing fields
  * Removing endpoints or resources
  * Changing authentication mechanisms
  * Modifying error response structures
  * Changing the meaning of existing fields

  When a new major version is released, we provide detailed migration guides and support both versions during a transition period.
</Accordion>

<Accordion title="Date-Based Headers">
  In addition to URL-based versioning, Prisme.ai supports date-based API version targeting for fine-grained compatibility:

  ```
  X-Prisme-API-Version: 2023-10-15
  ```

  This header requests the API implementation as it existed on that date, which can help maintain compatibility with a specific behavior even as minor updates are released.

  <Info>
    Date-based versioning is optional. If not specified, you'll get the latest implementation of the requested major version.
  </Info>
</Accordion>

## Using API Versions

<Steps>
  <Step title="Specify the Version in the URL">
    Always include the version in the URL path:

    ```bash theme={null}
    # Example API request with version in URL
    curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
         -H "Authorization: Bearer YOUR_TOKEN"
    ```
  </Step>

  <Step title="Optional: Use Date-Based Versioning">
    For more precise versioning, add the `X-Prisme-API-Version` header:

    ```bash theme={null}
    # Example API request with date-based versioning
    curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
         -H "Authorization: Bearer YOUR_TOKEN" \
         -H "X-Prisme-API-Version: 2023-10-15"
    ```
  </Step>

  <Step title="Check Version-Specific Documentation">
    Always refer to the documentation for your specific API version. Features and endpoints may differ between versions.
  </Step>

  <Step title="Plan for Version Migrations">
    Stay informed about version deprecations and plan migrations accordingly:

    * Subscribe to the Prisme.ai developer newsletter
    * Check the changelog for deprecation notices
    * Test your integration with beta versions
    * Allow time to migrate before version retirement
  </Step>
</Steps>

## Version Lifecycle

Prisme.ai API versions go through several stages:

<CardGroup cols="4">
  <Card title="Beta" icon="flask">
    * Early access preview
    * May change without notice
    * Not recommended for production
    * Labeled with "beta" in docs
  </Card>

  <Card title="Stable" icon="circle-check">
    * Fully supported
    * Backward compatible updates only
    * Recommended for production use
    * Comprehensive documentation
  </Card>

  <Card title="Deprecated" icon="triangle-exclamation">
    * Still functional but will be retired
    * No new features added
    * Security patches only
    * Migration recommendations provided
  </Card>

  <Card title="Retired" icon="box-archive">
    * No longer available
    * Returns 410 Gone response
    * Redirects to documentation
    * No support provided
  </Card>
</CardGroup>

## Version Deprecation Process

<Steps>
  <Step title="Announcement">
    When a version is deprecated:

    * Public announcement at least 12 months before retirement
    * Email notification to active users of the version
    * Deprecation notice in API responses (via headers)
    * Documentation updated with migration guidance
  </Step>

  <Step title="Sunset Period">
    During the deprecation period:

    * Version continues to function normally
    * Security patches are applied
    * No new features are added
    * Warning headers are included in responses

    ```
    X-Prisme-API-Deprecation: This API version is deprecated and will be retired on 2025-12-31. Please migrate to v2.
    ```
  </Step>

  <Step title="Retirement">
    When a version is retired:

    * Endpoints return 410 Gone status code
    * Response includes migration information
    * Requests are no longer processed
    * Documentation moves to archive section
  </Step>
</Steps>

## Best Practices

<CardGroup cols="2">
  <Card title="Specify Exact Versions" icon="code">
    Always explicitly specify the API version in your code:

    ```javascript theme={null}
    const API_VERSION = 'v2';
    const API_BASE_URL = `https://api.studio.prisme.ai/${API_VERSION}`;

    async function fetchWorkspaces() {
      const response = await fetch(`${API_BASE_URL}/workspaces`, {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      });
      return response.json();
    }
    ```
  </Card>

  <Card title="Handle Version Headers" icon="rectangle-list">
    Check for version-related response headers:

    ```javascript theme={null}
    function checkVersionStatus(response) {
      const deprecationNotice = response.headers.get('X-Prisme-API-Deprecation');
      if (deprecationNotice) {
        console.warn(`API Version Warning: ${deprecationNotice}`);
      }
      
      const versionUsed = response.headers.get('X-Prisme-API-Version-Used');
      console.log(`API Version Used: ${versionUsed}`);
    }
    ```
  </Card>

  <Card title="Test with Beta Versions" icon="vial">
    Test your integrations with beta versions early:

    ```javascript theme={null}
    // Toggle between stable and beta for testing
    const USE_BETA = process.env.NODE_ENV === 'development';
    const API_VERSION = USE_BETA ? 'v3' : 'v2';
    const API_BASE_URL = `https://api.studio.prisme.ai/${API_VERSION}`;
    ```
  </Card>

  <Card title="Monitor Deprecation Notices" icon="bell">
    Set up monitoring for deprecation notices:

    ```javascript theme={null}
    // Example monitoring function
    function monitorDeprecationNotices(response) {
      const deprecationNotice = response.headers.get('X-Prisme-API-Deprecation');
      if (deprecationNotice) {
        // Log to monitoring system
        sendAlert(`API Deprecation Notice: ${deprecationNotice}`);
      }
    }
    ```
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols="3">
  <Card title="Introduction" icon="book-open" href="/api-reference/introduction">
    Return to API overview
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about authentication methods
  </Card>

  <Card title="SDKs" icon="code" href="/api-reference/sdks">
    Use the official SDK repositories when building API integrations
  </Card>
</CardGroup>