API Versioning¶

Vellocity uses URL-based versioning to provide stability guarantees for API consumers.

Version Scheme¶

All stable endpoints live under the /api/v1 prefix:

https://api.vell.ai/api/v1/partners/profile

Stability Guarantees¶

Promise	Detail
Frozen contract	v1 routes will not change once released
Bug fixes only	Fixes that don't break request/response contracts
No field removal	Existing response fields are never removed
Additive changes	New optional fields may be added to responses
Breaking changes	Require a new version (e.g., `/api/v2`)

Deprecation Policy¶

When an endpoint is deprecated:

A Deprecation header is added to all responses
A Sunset header indicates the removal date
The endpoint continues to function until the sunset date
Documentation is updated with migration instructions

Deprecation Headers¶

Deprecation: true
Sunset: Thu, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.vell.ai/api/versioning/#migration>; rel="deprecation"

Current Migration: Unversioned to v1¶

Sunset date: 2026-07-01

31 endpoints are being migrated from unversioned paths (/api/...) to versioned paths (/api/v1/...). Both paths work during the migration window.

What's Changing¶

Before (deprecated)	After (stable)
`/api/agents/audit/`	`/api/v1/agents/audit/`
`/api/agents/audit/{agent}/metrics`	`/api/v1/agents/audit/{agent}/metrics`
`/api/agents/audit/{agent}/migrate`	`/api/v1/agents/audit/{agent}/migrate`
`/api/dry-run/sessions/`	`/api/v1/dry-run/sessions/`
`/api/dry-run/sessions/start`	`/api/v1/dry-run/sessions/start`
`/api/dry-run/sessions/{token}/message`	`/api/v1/dry-run/sessions/{token}/message`
`/api/affiliates/`	`/api/v1/affiliates/`
`/api/affiliates/update-reference`	`/api/v1/affiliates/update-reference`

Migration Checklist¶

Update base URL from /api/ to /api/v1/ in your integration
Verify authentication still works (same API key, same header format)
Test all endpoints against the v1 paths
Remove any deprecated path references before 2026-07-01

Quick migration

In most cases, you only need to change the base URL prefix. Request and response formats are identical between unversioned and v1 paths.

New v1-Only Endpoints¶

These endpoints are available exclusively under /api/v1 and have no unversioned equivalent:

API Domain	Endpoints	Documentation
Partner API	`/v1/partners/*`	Partner API
Content Workflow	`/v1/content-workflow/*`	Content Workflow
MCP Server	`/v1/mcp`	MCP Server
GTM Schedule	`/v1/gtm-schedule/*`	GTM Schedule
Invoice Receipts	`/v1/invoice-receipts/*`	Invoices
Webhooks	`/v1/partners/webhooks/*`	Webhooks

Version Lifecycle¶

stateDiagram-v2
    [*] --> Active: Version released
    Active --> Deprecated: New version available
    Deprecated --> Sunset: Grace period ends
    Sunset --> [*]: Endpoints removed

    note right of Active
        Full support, bug fixes
    end note
    note right of Deprecated
        Works but sends deprecation headers
        Minimum 6-month grace period
    end note

FAQ¶

Q: Will v1 endpoints ever break? No. Once released, v1 contracts are frozen. If we need to make breaking changes, we'll release v2 with a migration period.

Q: Can I use unversioned endpoints? They work today but will be removed on 2026-07-01. Migrate to /api/v1 paths now.

Q: How will I know about new versions? We announce new versions via the changelog, email notifications, and deprecation response headers.