Versioning

Learn how Lia's API versioning works and how to specify API versions in your requests.

Version Format

API versions use the format: YYYY-MM-DD.nickname

• Date: Point-in-time version (e.g., 2025-12-15)

• Nickname: Translation/language themed name (e.g., babel, rosetta, lingua)

Example: 2025-12-15.babel

Each version nickname represents a set of backward-compatible changes. Breaking changes require a new nickname.

Specifying a Version

Specify the API version using the X-Lia-Api-Version header in your requests:

curl https://api.acolad.ai/translate/text \
  -H "X-Lia-Api-Version: 2025-12-15.babel" \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "targetLang": "fr"}'

Supported Formats

You can specify the version in multiple ways:

Format	Example	Description
Full version	2025-12-15.babel	Date + nickname (recommended for stability)
Nickname only	babel	Uses the version with that nickname
Latest alias	latest	Uses the latest active version
No header	(omit header)	Defaults to latest active version

For production applications, always specify a full version (date + nickname) to ensure stable behavior.

Version Lifecycle

API versions progress through three lifecycle stages:

Active

Current production version, fully supported with all features.

Deprecated

Sunset date announced, still functional, but migration recommended. You'll receive deprecation headers in responses.

Retired

No longer available. Returns 410 Gone error with instructions to upgrade.

When a version is deprecated, you'll receive deprecation headers. Plan to migrate before the sunset date.

Response Headers

All API responses include version information in the response headers:

Standard Headers

• X-Lia-Api-Version: The version used for this request (e.g., 2025-12-15.babel)

• X-Lia-Api-Version-Latest: The latest active version

Deprecation Headers

For deprecated versions, additional headers are included:

• Deprecation: true - Indicates the version is deprecated

• Sunset: <RFC 7234 date> - Date when the version will be retired

• Warning: "This API version will sunset on YYYY-MM-DD" - Human-readable warning

Example response headers for deprecated version:

X-Lia-Api-Version: 2025-01-01.legacy
X-Lia-Api-Version-Latest: 2025-12-15.babel
Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Warning: This API version will sunset on 2026-07-01

Error Handling

Unknown Version

If you specify an unknown or invalid version, you'll receive a 400 Bad Request error:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Unknown API version: 2024-01-01.unknown. Available versions: 2025-12-15.babel"
  }
}

Retired Version

If you try to use a retired version, you'll receive a 410 Gone error:

{
  "error": {
    "code": "GONE",
    "message": "API version 2024-06-01.legacy has been retired. Please upgrade to 2025-12-15.babel."
  }
}

Best Practices

Always Specify a Version

Don't rely on the default behavior. Explicitly specify the version in all production requests:

# ✅ Good - Explicit version
curl -H "X-Lia-Api-Version: 2025-12-15.babel" https://api.acolad.ai/whoami

# ❌ Bad - Relying on default
curl https://api.acolad.ai/whoami

Pin to a Specific Version

Use the full format (YYYY-MM-DD.nickname) for production to ensure stable behavior:

# ✅ Good - Full version for stability
curl -H "X-Lia-Api-Version: 2025-12-15.babel" https://api.acolad.ai/translate/text

# ⚠️ Okay for development - Nickname only
curl -H "X-Lia-Api-Version: babel" https://api.acolad.ai/translate/text

# ❌ Bad for production - Latest alias
curl -H "X-Lia-Api-Version: latest" https://api.acolad.ai/translate/text

Monitor Deprecation Headers

Check response headers for deprecation warnings and plan migrations before sunset dates:

const response = await fetch('https://api.acolad.ai/translate/text', {
  headers: {
    'X-Lia-Api-Version': '2025-12-15.babel',
    'x-api-key': 'your_api_key'
  }
});

// Check for deprecation
if (response.headers.get('Deprecation') === 'true') {
  const sunset = response.headers.get('Sunset');
  console.warn(`API version will be retired on ${sunset}`);
  // Plan migration to latest version
}

Test New Versions

Use a staging environment to test new versions before upgrading production:

// Staging environment - Test latest version
const STAGING_VERSION = 'latest';

// Production environment - Use stable version
const PRODUCTION_VERSION = '2025-12-15.babel';

const version = process.env.NODE_ENV === 'production'
  ? PRODUCTION_VERSION
  : STAGING_VERSION;

Available Versions

Version	Nickname	Status	Sunset Date	Release Notes
2025-12-15.babel	babel	Active	-	Initial public API release