Skip to main content

​
API Versioning Guide

The Firma API uses header-based versioning via the X-API-Version header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

​
How to Specify a Version

Include the X-API-Version header in your request: 
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
If the X-API-Version header is omitted, the API defaults to the current stable version (currently 1).

​
Version Lifecycle

Each API version goes through three stages:
StatusDescriptionBehavior
activeFully supported versionNormal responses with X-API-Version header
deprecatedStill functional but scheduled for removalResponses include deprecation warning headers
sunsetRemoved from serviceReturns 410 Gone error

​
Response Headers

​
For Active Versions

X-API-Version: 1

​
For Deprecated Versions

When a version is deprecated, the following headers are included in every response: 
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
HeaderDescription
DeprecationRFC 8594 compliant - Date when the version was deprecated
SunsetRFC 8594 compliant - Date when the version will be removed
X-Deprecated-MessageHuman-readable warning message

​
Error Responses

​
Invalid Version Header

// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}

​
Unsupported Version

// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}

​
Sunset Version (Removed)

// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}

​
Breaking Changes Policy

Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.
When a new major version is released:
  1. The previous version is marked as deprecated
  2. You’ll receive warning headers for a recommended 6-month deprecation period
  3. After the sunset date, the old version returns 410 Gone

​
What Constitutes a Breaking Change?

Breaking changes include:
  • Removing or renaming existing fields
  • Changing field types or validation rules
  • Removing endpoints
  • Changing authentication requirements
  • Modifying rate limits significantly
Non-breaking changes include:
  • Adding new optional fields
  • Adding new endpoints
  • Adding new enum values (if your client handles unknown values gracefully)
  • Improving error messages

​
Best Practices

Implement automated checks in your API client code to detect Deprecation and Sunset headers. Log warnings when these headers are present.
const response = await fetch(url, options);

if (response.headers.get('Deprecation')) {
  console.warn('API Deprecation Warning:', {
    deprecation: response.headers.get('Deprecation'),
    sunset: response.headers.get('Sunset'),
    message: response.headers.get('X-Deprecated-Message')
  });
}
Rather than relying on the default version, always specify the X-API-Version header explicitly. This prevents unexpected breaking changes when the default version changes.
// Good - explicit version
headers: { 'X-API-Version': '1' }

// Avoid - relies on default
headers: { }
Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
  • New version releases
  • Deprecation schedules
  • Breaking changes
  • Migration guides
When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
  • Identify breaking changes in your implementation
  • Update your code and dependencies
  • Test thoroughly in staging
  • Deploy with confidence before the deadline

​
Current Version Status

The current active version is v1 with no deprecation scheduled at this time.
When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

Authentication

Learn about API key authentication and JWT tokens

Complete Setup Guide

Get started with the Firma API

Webhooks

Set up webhook notifications for events

API Reference

Browse all API endpoints