Migrate from /v1 to /v2
This page shows how to move an integration from /v1 on api.cloudraker.com to API v2. /v1 continues without changes, so you can move one route at a time.
/v1 has no end date now. When CloudRaker sets a date, /v1 answers get Deprecation, Sunset and Link headers. The notice is 6 months. The Link header names this page.Compare the APIs
Move an integration
- Find the slug of your organization in the Settings page of Dash.
- Create a
crk_key. Select the scope of each capability that you call. - Add your webhook endpoints on the Webhooks page of Dash.
- Change your webhook verifier. Read Move your webhooks.
- Change one route: the host and key, the wait and the body.
- Change the code that reads the answer. Use the Job object map.
- Test the route with a test key, then deploy it with a live key.
- Move the next route.
Read a run that started on /v1 through its /v1 URL until it ends. Do not send its document to /v2 again. That starts a second job and uses credits again.
Keep your /v1 key until no code calls /v1. Some routes have no /v2 route.
The TypeScript SDK builds the host from the key, sends the idempotency key and verifies webhooks.
Change the host and the key
{slug} is the slug of your organization. The slug never changes, and each crk_ key contains it.
A /v1 key does not work on /v2. The answer is 401 invalid_api_key. A crk_ key does not work on /v1. A crk_ key also works only on the host of its own organization.
A crk_ key can call only the capabilities in its scopes. A missing scope gives 403 insufficient_scope.
Map the routes
Capabilities
Runs and webhooks
A /v1 run id does not work on /v2/jobs. A job id does not work on /v1/runs.
Routes with no /v2 route
Keep these routes on /v1, with your /v1 key.
Routes outside the /v1 notice
These routes do not get the Deprecation and Sunset headers.
Change the wait
?wait=N also works on /v2, but only from 1 to 90. ?wait=0 and a value above 90 give 400 wait_out_of_range. The Prefer header wins when both are present.
sign and transcribe default to respond-async. Send a preference for agents.
A slow call does not fail. At the end of the wait, the job continues and the answer is 202:
The body of the 202 is the same job. Read the job with GET /v2/jobs/{id} and Prefer: wait=N, a stream or a webhook.
wait=55 or less. Set the timeout of your HTTP client higher than the wait.Change the body
If a capability has a /v1 route with the same name, the body fields that are not in this table do not change. A body is JSON, with a maximum size of 1 MiB. Send a large file by URL.
/v1 returned metadata on each read. On /v2, keep your own map from the job id to your identifiers.
Read the Job object
The API keeps a job for 30 days. A later read gets 404 job_not_found.
Move your webhooks
Create new endpoints
/v1 saved endpoints are not shared with /v2. Add each endpoint again on the Webhooks page of Dash. Dash gives it a new whe_ id.
An old /v1 id in notify.endpoint gives 400 invalid_request, and the API creates no job.
Keep your /v1 endpoints until no /v1 run can send an event.
Change the verifier
A /v1 verifier does not verify a v2 webhook. Write a new verifier from Webhooks, or use verifyWebhook in the SDK.
Use jti to drop a delivery that you already processed.
The body also changes. data.job is the Job object.
Map the events
A job sends one event when it ends. /v1 sends both run.completed and processing.completed for one run.
Change the idempotency keys
The Idempotency-Key header stays. The rules change.
The API compares the method, the path and the body. A key lives for 24 hours. If your code sends one key with different bodies, change it to send a new key for each new request.
Read Idempotency.
Change the error codes
The error body stays the same. Switch on code and use retryable.
A job can fail after the API accepts it. The answer is then 200 with the job in the failed status. Read the job error codes and Errors.