API Migration Notice - Action Required

Effective Date: 2026-02-01 Sunset Date: 2026-07-01 Document Version: 1.0

---

Summary

We are migrating critical API endpoints to versioned paths under /api/v1 to establish stable API contracts. This migration improves API reliability and enables future enhancements without breaking existing integrations.

---

Affected Endpoints

The following API endpoints are being migrated to versioned paths:

Agent Audit & Migration API (23 endpoints)

Current (Deprecated)	New (v1)
GET /api/agents/audit/	GET /api/v1/agents/audit/
GET /api/agents/audit/company-analytics	GET /api/v1/agents/audit/company-analytics
GET /api/agents/audit/marketplace-metrics	GET /api/v1/agents/audit/marketplace-metrics
POST /api/agents/audit/recommend-configuration	POST /api/v1/agents/audit/recommend-configuration
POST /api/agents/audit/batch-migrate	POST /api/v1/agents/audit/batch-migrate
GET /api/agents/audit/capabilities/	GET /api/v1/agents/audit/capabilities/
POST /api/agents/audit/capabilities/estimate-cost	POST /api/v1/agents/audit/capabilities/estimate-cost
POST /api/agents/audit/capabilities/model-recommendation	POST /api/v1/agents/audit/capabilities/model-recommendation
POST /api/agents/audit/capabilities/{capability}/test	POST /api/v1/agents/audit/capabilities/{capability}/test
GET /api/agents/audit/{agent}/metrics	GET /api/v1/agents/audit/{agent}/metrics
GET /api/agents/audit/{agent}/validate	GET /api/v1/agents/audit/{agent}/validate
POST /api/agents/audit/{agent}/migrate	POST /api/v1/agents/audit/{agent}/migrate
POST /api/agents/audit/{agent}/rollback	POST /api/v1/agents/audit/{agent}/rollback
POST /api/agents/audit/{agent}/dry-run	POST /api/v1/agents/audit/{agent}/dry-run
POST /api/agents/audit/{agent}/challenge	POST /api/v1/agents/audit/{agent}/challenge
GET /api/agents/audit/{agent}/marketplace-readiness	GET /api/v1/agents/audit/{agent}/marketplace-readiness
POST /api/agents/audit/{agent}/preview-capability	POST /api/v1/agents/audit/{agent}/preview-capability
POST /api/agents/audit/{agent}/capability-models	POST /api/v1/agents/audit/{agent}/capability-models
POST /api/agents/audit/{agent}/dry-run-session	POST /api/v1/agents/audit/{agent}/dry-run-session

Dry Run Sessions API (7 endpoints)

Current (Deprecated)	New (v1)
GET /api/dry-run/sessions/	GET /api/v1/dry-run/sessions/
POST /api/dry-run/sessions/start	POST /api/v1/dry-run/sessions/start
GET /api/dry-run/sessions/{token}	GET /api/v1/dry-run/sessions/{token}
POST /api/dry-run/sessions/{token}/message	POST /api/v1/dry-run/sessions/{token}/message
PUT /api/dry-run/sessions/{token}/persona	PUT /api/v1/dry-run/sessions/{token}/persona
POST /api/dry-run/sessions/{token}/reset	POST /api/v1/dry-run/sessions/{token}/reset
POST /api/dry-run/sessions/{token}/end	POST /api/v1/dry-run/sessions/{token}/end

Affiliates API (1 endpoint)

Current (Deprecated)	New (v1)
POST /api/affiliates/update-reference	POST /api/v1/affiliates/update-reference

Webhooks (New versioned path available)

For new webhook integrations, prefer the versioned endpoint:

Legacy (Maintained)	New (v1)
GET/POST /webhooks/{gateway}	GET/POST /webhooks/v1/{gateway}

Note: Legacy webhook routes will be maintained indefinitely for existing third-party integrations.

---

What You Need to Do

Step 1: Update Your API Base URL

Change your API calls to use the versioned path:

- const API_BASE = 'https://api.example.com/api';
+ const API_BASE = 'https://api.example.com/api/v1';

Step 2: Test Your Integration

Before the sunset date, test all your API calls against the new versioned endpoints:

# Example: Test the Agent Audit API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/api/v1/agents/audit/

# Example: Test Dry Run Sessions
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/api/v1/dry-run/sessions/

Step 3: Complete Migration Before Sunset

Ensure all your systems are updated before 2026-07-01.

---

Deprecation Headers

During the migration period, deprecated endpoints will return the following HTTP headers:

Header	Value	Description
Deprecation	true	Indicates the endpoint is deprecated
Sunset	2026-07-01	Date when the endpoint will be removed
Link	</api/v1/...>; rel="successor-version"	Link to the new endpoint
X-Deprecation-Notice	Human-readable message	Migration instructions

Example Response Headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: 2026-07-01
Link: </api/v1/agents/audit>; rel="successor-version"
X-Deprecation-Notice: This endpoint is deprecated. Please migrate to /api/v1/agents/audit. Sunset date: 2026-07-01.

---

API Documentation

Updated API documentation is available:

• OpenAPI Specification: docs/openapi/api-v1-versioned-endpoints.yaml
• Versioning Audit Report: docs/audits/API_VERSIONING_AUDIT.md
• Implementation Plan: docs/API_VERSIONING_IMPLEMENTATION_PLAN.md

---

Versioning Policy

The v1 API follows these guarantees:

1. Frozen Contract: v1 routes are frozen once released
2. Bug Fixes Only: Only bug fixes are allowed; breaking changes require v2
3. Deprecation Notice: At least 6 months notice before any endpoint removal
4. Header Warnings: Deprecation headers are always provided

---

Timeline

Date	Milestone
2026-02-01	Migration begins - both old and new endpoints work
2026-02-01	Deprecation headers added to legacy endpoints
2026-05-01	Final reminder sent to consumers
2026-07-01	Sunset - Legacy endpoints may return 410 Gone

---

Support

If you have questions or need assistance with the migration:

• Documentation: See the files listed above
• Issues: Contact the engineering team

---

Changelog

Version	Date	Changes
1.0	2026-01-21	Initial migration notice

---

Document maintained by the Engineering Team