Skip to main content
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

URL-Based Versioning

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.

Major Versions

New major versions (v1, v2, v3) are released when:
  • Introducing breaking changes
  • Significantly restructuring resources
  • Changing fundamental behavior

Minor Updates

Updates within a version (v2.1, v2.2) for:
  • Adding new endpoints
  • Extending existing endpoints
  • Bug fixes and improvements

Version Lifecycle

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

​
Current API Versions

  • v2 (Current)
  • v1 (Deprecated)
  • v3 (Beta)
Version 2 is the current stable API version.

Status

Stable and fully supported

Base URL

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

Documentation

This documentation describes the v2 API

Retirement Date

No planned retirement date
Key Features:
  • Comprehensive workspace management
  • Document and knowledge base operations
  • Agent creation and management
  • Enhanced automation capabilities
  • Fine-grained permissions system

​
Version Compatibility

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
Beta versions do not follow the backward compatibility guarantee and may change without notice.
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.
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.
Date-based versioning is optional. If not specified, you’ll get the latest implementation of the requested major version.

​
Using API Versions

1

Specify the Version in the URL

Always include the version in the URL path:
# Example API request with version in URL
curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
     -H "Authorization: Bearer YOUR_TOKEN"
2

Optional: Use Date-Based Versioning

For more precise versioning, add the X-Prisme-API-Version header:
# 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"
3

Check Version-Specific Documentation

Always refer to the documentation for your specific API version. Features and endpoints may differ between versions.
4

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

​
Version Lifecycle

Prisme.ai API versions go through several stages:

Beta

  • Early access preview
  • May change without notice
  • Not recommended for production
  • Labeled with “beta” in docs

Stable

  • Fully supported
  • Backward compatible updates only
  • Recommended for production use
  • Comprehensive documentation

Deprecated

  • Still functional but will be retired
  • No new features added
  • Security patches only
  • Migration recommendations provided

Retired

  • No longer available
  • Returns 410 Gone response
  • Redirects to documentation
  • No support provided

​
Version Deprecation Process

1

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
2

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.
3

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

​
Best Practices

Specify Exact Versions

Always explicitly specify the API version in your code:
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();
}

Handle Version Headers

Check for version-related response headers:
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}`);
}

Test with Beta Versions

Test your integrations with beta versions early:
// 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}`;

Monitor Deprecation Notices

Set up monitoring for deprecation notices:
// 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}`);
  }
}

​
Next Steps

Introduction

Return to API overview

Authentication

Learn about authentication methods

Playground

Try out the API with interactive examples