API Versioning

This document outlines the versioning strategy for the Girard AI API, including backward compatibility guarantees, deprecation policies, and migration guidelines.

Overview

The Girard AI API uses URL path versioning with the following format:

https://www.girardai.com/api/{version}/{resource}

Example:

https://www.girardai.com/api/v1/workflows
https://www.girardai.com/api/v1/workflows/{id}/execute

Current Version

Versioning Strategy

1. URL Path Versioning

• Version is explicitly included in the URL path (e.g., /api/v1/)
• This approach is cacheable, explicit, and easy to route
• Clients specify the exact version they're integrating with

2. Semantic Versioning

We follow semantic versioning principles:

• Major versions (v1, v2, v3): Indicate breaking changes
• Minor updates: Backward-compatible additions within a version
• Patch updates: Bug fixes that don't change the API contract

3. Stability Levels

Backward Compatibility Guarantees

Within a major version (e.g., all of v1), we guarantee:

What WILL NOT change:

• ✅ Existing endpoint URLs and HTTP methods
• ✅ Required request parameters and their types
• ✅ Response structure for successful requests (fields won't be removed)
• ✅ Error response format and standard error codes
• ✅ Authentication mechanism (X-API-Key header)
• ✅ Rate limiting headers format

What MAY change (additive):

• ➕ New optional request parameters
• ➕ New fields in response objects
• ➕ New endpoints
• ➕ New error codes (existing codes remain stable)
• ➕ New webhook event types

Deprecation Policy

Timeline

1. Announcement (Day 0): Deprecation announced via:

   • API changelog
   • Email to API key owners
   • Blog post
   • In-app notification

2. Migration Period (12 months minimum):

   • Both old and new versions are supported
   • Deprecated endpoints return X-API-Deprecated header
   • Migration guides and tooling provided

3. Sunset (After 12+ months):

   • Deprecated version returns 410 Gone
   • Final warning emails sent 30/7/1 days before

Deprecation Headers

Deprecated endpoints include:

X-API-Deprecated: true
X-API-Sunset: 2027-01-15T00:00:00Z
X-API-Deprecation-Notice: This endpoint is deprecated. Migrate to /api/v2/workflows

Migration Guidelines

When a New Version is Released

1. Review the changelog for breaking changes
2. Read the migration guide for your specific use case
3. Update your base URL from /api/v1 to /api/v2
4. Test in a staging environment before production
5. Update error handling for any new error codes
6. Monitor deprecation warnings in your logs

Common Migration Patterns

URL Updates

- https://www.girardai.com/api/v1/workflows
+ https://www.girardai.com/api/v2/workflows

Request Body Changes

// v1
{
  "input": "Generate a blog post",
  "model": "gpt-4"
}

// v2 (hypothetical)
{
  "prompt": "Generate a blog post",
  "config": {
    "model": "gpt-4"
  }
}

Error Handling Across Versions

All versions use the same error format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { },
    "hint": "Suggested resolution"
  }
}

Version-Specific Error Codes

SDK Support

When new API versions are released:

1. Existing SDKs continue to work with the version they target
2. New SDK versions are released to support new API versions
3. SDK deprecation follows the same 12-month policy

Best Practices for API Consumers

Do's

• ✅ Always specify the API version explicitly in your requests
• ✅ Monitor the X-API-Deprecated header in responses
• ✅ Subscribe to the API changelog (RSS or email)
• ✅ Test version migrations in staging before production
• ✅ Use official SDKs when available (handles versioning automatically)

Don'ts

• ❌ Don't rely on unversioned endpoints
• ❌ Don't assume response structure won't add new fields
• ❌ Don't ignore deprecation warnings
• ❌ Don't wait until the last minute to migrate

Changelog

v1 (January 2026)

Initial release including:

• Workflow management (CRUD)
• Workflow execution
• Run status and history
• Rate limiting
• API key authentication

Questions?

• Documentation: https://www.girardai.com/dashboard/api-docs
• OpenAPI Spec: https://www.girardai.com/openapi.json
• Support: support@girardai.com