Migrating from API v1 to API v2

CloudNexus API v2 introduces standardized authentication, improved pagination, structured error responses, and new resource capabilities. Follow this guide to transition your integrations smoothly before v1 sunset.

⚠️

Deprecation Notice: API v1 will be fully deprecated and removed on March 31, 2026. All integrations must migrate to v2 before this date. Existing v1 API keys will remain valid but will only route to v2 endpoints after the sunset date.

Overview of Changes

API v2 is designed to be more predictable, secure, and performant. While most v1 calls can be adapted with minimal changes, several breaking changes require attention.

Area	v1 Behavior	v2 Behavior	Impact
Base URL	`api.cloudnexus.io/v1`	`api.cloudnexus.io/v2`	Breaking
Authentication	`Authorization: Bearer {key}`	`X-API-Key: {key}` + Scoped tokens	Breaking
Pagination	Offset-based (`skip`, `limit`)	Cursor-based (`page_cursor`, `per_page`)	Breaking
Error Format	Plain text / inconsistent JSON	Standardized RFC 7807 Problem JSON	Changed
Rate Limits	Global header `X-RateLimit`	Standard `RateLimit-*` headers + burst support	Improved

Authentication Changes

v1 used a single Bearer token for all requests. v2 requires API keys to be passed via the X-API-Key header. We recommend generating new scoped keys with the principle of least privilege.

v1 (Legacy)

curl -X GET https://api.cloudnexus.io/v1/servers \
  -H "Authorization: Bearer cn_live_8f9a2b..."

v2 (Current)

curl -X GET https://api.cloudnexus.io/v2/servers \
  -H "X-API-Key: cn_live_8f9a2b..." \
  -H "Content-Type: application/json"

ℹ️

Tip: Generate scoped keys in your dashboard under Settings → API Keys. Assign only the permissions your integration needs (e.g., servers:read, billing:write).

Pagination & Query Parameters

v1 used offset-based pagination, which can cause performance issues on large datasets. v2 switches to cursor-based pagination for consistent, stable iteration.

Request Format

GET /v1/servers?skip=0&limit=20

GET /v2/servers?page_cursor=eyJpZCI6MTAwfQ&per_page=20

Response Structure

JSON Response

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "prev_cursor": "eyJpZCI6ODB9",
    "has_more": true,
    "total_count": 482
  }
}

Error Handling

All v2 errors return a structured JSON object following the RFC 7807 specification. This makes parsing and retry logic significantly more reliable.

v2 Error Response (403 Forbidden)

{
  "type": "https://api.cloudnexus.io/errors/forbidden",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "API key lacks 'servers:write' scope.",
  "code": "INSUFFICIENT_SCOPE",
  "request_id": "req_9x8c7v6b5n4m"
}

✅

Best Practice: Always log the request_id when reporting issues. Our support team can trace any v2 request in under 30 seconds using this identifier.

Migration Checklist

Use this step-by-step guide to transition your applications without downtime.

✓
Update Base URLs: Replace all references to /v1/ with /v2/ in your codebase and config files.
✓
Switch Authentication: Replace Authorization: Bearer with X-API-Key. Generate scoped keys in the dashboard.
✓
Implement Cursor Pagination: Replace skip/limit logic with cursor-based iteration using next_cursor.
✓
Update Error Parsing: Adjust error handlers to expect the new RFC 7807 JSON structure.
✓
Test in Staging: Use the ?preview=v2 query parameter on v1 endpoints to test responses in isolation.
✓
Monitor & Switch: Deploy to production, monitor request_id logs, and remove v1 fallbacks.

Migration Timeline

Oct 1, 2024

API v2 enters General Availability. v1 remains stable.

Jan 15, 2025

v1 endpoints return Deprecation-Warning headers.

Oct 1, 2025

v1 enters maintenance mode. Only critical bug fixes applied.

Mar 31, 2026

v1 sunset. All traffic routes to v2. Legacy keys auto-migrate.

Need Help?

Our engineering team is here to assist with your migration. You can reach us through:

📧 api-migration@cloudnexus.io
💬 Engineering Discord (API Migration channel)
📖 Full v2 API Reference