API v4 is the current major version. If you're still on v3, this guide covers the key differences, the migration path, and the timeline. v3 remains supported through its announced sunset; migrate before then.
What changed in v4
v4 standardizes the response envelope (consistent error shape with code, message, and request_id — see API error codes reference), adds batch endpoints for bulk operations (see Rate limits and quotas), introduces scoped API keys (see Authentication and API keys), and normalizes timestamps to ISO-8601 UTC across all resources. Resource paths remain familiar.
Migration steps
Create a new scoped v4 key, point your base URL at api.turgo.ai/v1 (the current line), update error handling to branch on the code field, switch bulk loops to the batch endpoints, and adjust any timestamp parsing to ISO-8601 UTC. The SDKs (see Node.js SDK and Python SDK) target v4 and handle most of this for you.
Testing the switch
Run v3 and v4 side by side against a read-only key first, compare responses, then cut writes over. Use Idempotency-Key on creates during the transition so retries don't double-create.
Timeline and help
v3 is deprecated with a sunset date; migrate before it. If you hit a snag, contact support with your request_id and the endpoint in question.
