Skip to navigation

Migrate from /v1 to /v2

Change the host, the key and the wait. Then read one Job object.
View as Markdown

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

Topic/v1/v2
API hosthttps://api.cloudraker.com/v1https://{slug}.cloudraker.run/v2
CredentialAn organization API key from Admin, then API keysA crk_ key from Dash, or an OIDC trust
Hold the request?wait=N: 0 to 120 seconds, default 60Prefer: wait=N: 1 to 90 seconds, default 30 for most capabilities
Answer after the wait202 with statusUrl in the body202 with the job, and the Location and Retry-After headers
ResultOne run object for each capability, for example extract_runOne Job object for all capabilities
Webhook in the bodywebhooknotify
Saved webhooksPOST /v1/webhooksThe Webhooks page of Dash
Webhook signaturex-rk1-signature: an ES256 JWT, with one JWKS for all customersx-cr-signature: an RS256 JWT, with one JWKS for each organization
IdempotencyThe same key returns the first run. The API does not compare the body.The same key with another body gives 409 idempotency_key_reused.
Rate limits67 requests per minute for each organizationLimits by plan. Read Rate limits.
Error bodycode, message, retryable, requestId, docUrlThe same body. Some codes change.

Move an integration

  1. Find the slug of your organization in the Settings page of Dash.
  2. Create a crk_ key. Select the scope of each capability that you call.
  3. Add your webhook endpoints on the Webhooks page of Dash.
  4. Change your webhook verifier. Read Move your webhooks.
  5. Change one route: the host and key, the wait and the body.
  6. Change the code that reads the answer. Use the Job object map.
  7. Test the route with a test key, then deploy it with a live key.
  8. Move the next route.
Test keys have their own rate limits, but their jobs use real paperwork credits. A test key cannot start an agent.

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

curl -X POST "https://api.cloudraker.com/v1/parse?wait=60" \
-H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'

{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

/v1 route/v2 routeChange
POST /v1/parsePOST /v2/parseNone.
POST /v1/parse with the processing value transcribe or transcribe_diarizePOST /v2/transcribeThe default is respond-async.
POST /v1/extractPOST /v2/extractNone.
POST /v1/classifyPOST /v2/classifyNone.
POST /v1/splitPOST /v2/splitclassifyRunId takes only a /v1 clr_ run id. After you move classify to /v2, send segments.
POST /v1/fillPOST /v2/fillNone.
POST /v1/redactPOST /v2/redactNone.
POST /v1/signPOST /v2/signThe default is respond-async. The job reaches needs_input when the envelope opens. To void an envelope or resend a signer link, keep this route on /v1.
POST /v1/composePOST /v2/generateRenders a saved template. The output is a file reference. There is no raw PDF answer.
POST /v1/files/{ref}/convert/markdown, /convert/pdf, /convert/imagePOST /v2/convertOne route for all conversions. The output is a file.
POST /v1/files/{ref}/split/pages, POST /v1/files/stitchPOST /v2/convertOne route for all conversions. The output is a file.
POST /v1/files/{ref}/redline, /v1/redline/{sessionId}/*/v2/redline/*A new session takes a file URL only. An id gives 400 invalid_request. The next two rows show the routes that change.
POST /v1/redline/{sessionId}/flush/v2/redline/{sessionId}/exportThe route name changes. The answer is a Job object, not a 201 with a file. The job output is a file reference.
POST /v1/redline/{sessionId}/suggestions/apply/v2/redline/{sessionId}/suggestions/applyThe answer is a Job object, not a 200 with the new revision. Read the job as for any other capability.

Runs and webhooks

/v1 route/v2 routeChange
GET /v1/runsGET /v2/jobsNeeds the jobs:read scope. Use capability=extract, not object=extract_run.
GET /v1/runs/{id}GET /v2/jobs/{id}With Prefer: wait=N, the answer is always 200 with the job.
POST /v1/runs/{id}/cancelPOST /v2/jobs/{id}/cancelOnly the credential that created the job can cancel it.
GET /v1/runs/{id}/output/{name}Read the URLs in outputRead the output of a job.
/v1/webhooks, /v1/webhooks/{id}The Webhooks page of DashDash manages v2 endpoints.
GET /v1/webhooks/jwks.jsonGET /.well-known/jwks.jsonOne JWKS for each organization, on its API host.

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.

/v1 routesNote
POST /v1/compose/batch, /v1/compose/configs/*POST /v2/generate renders a saved template one time. Create the template on /v1.
POST /v1/pipelineCall each capability on /v2, or keep the pipeline on /v1.
POST /v1/extract/batchSend one POST /v2/extract for each file.
/v1/files, /v1/files/{id}/v2 has no upload route. The id of a POST /v1/files file works as { "id": "…" } on /v2.
/v1/spaces/*/v2 has no spaces. This includes the capability routes under a space.
/v1/templates/*Manage templates on /v1.
/v1/actions/*, /v1/extract/configs/*, /v1/classify/configs/*, /v1/fill/configs/*, /v1/redact/configs/*Manage saved configs on /v1. An action in the body of POST /v2/extract or POST /v2/classify still works.
/v1/agents/*, /v1/agent-runs/*POST /v2/agents/{base}/{agent} starts a Run agent. It does not replace these routes.
/v1/paperwork-agents/*, /v1/work-sessions/*Keep these routes on /v1.
/v1/automations/*, /v1/triggers/*, /v1/embeds/*Keep these routes on /v1.
/v1/realtime/transcriptions/*POST /v2/transcribe reads a file. It does not stream live audio.
DELETE /v1/runs/{id}, POST /v1/runs/{id}/keepThe API keeps a job for 30 days. /v2 has no purge and no keep.
/v1/runs/{id}/audit, /envelope, /void, /signers/{signerId}/resendThese routes need a /v1 sgr_ run id. A /v2 sign job has no sgr_ id while the envelope is open, so these routes do not apply to it. If you need them, keep POST /v1/sign on /v1.

Routes outside the /v1 notice

These routes do not get the Deprecation and Sunset headers.

RouteNote
/v1/signing/*The RakeSign API. It stays on /v1.
/openai/v1/*The OpenAI-compatible API. It has no /v2 route.
/processAn older route with no version. It has no /v2 route.
/meGET /v2/me returns the credential of the request, not a user.
/api-keysThese routes manage /v1 keys. Dash manages crk_ keys.

Change the wait

/v1/v2
?wait=60Prefer: wait=60
?wait=0Prefer: respond-async
?wait=91 to ?wait=120Prefer: wait=90 or less, then continue from the 202
No wait (default 60)No preference. The default is wait=30 for most capabilities.

?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:

HTTP/1.1 202 Accepted
Location: /v2/jobs/job_01JC9M…
Retry-After: 5
Preference-Applied: wait=30

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.

Behind a proxy with a 60-second idle timeout, use wait=55 or less. Set the timeout of your HTTP client higher than the wait.

Change the body

/v1 input/v2 inputChange
webhook: { "url": "…" }notify: { "url": "…" }Rename the field. webhook in the body gives 400 invalid_request.
webhook: { "id": "whe_…" }notify: { "endpoint": "whe_…" }Use the id of a v2 endpoint. Read Move your webhooks.
ttlRemove itttl in the body gives 400 invalid_request. The API keeps a job for 30 days.
metadatametadataThe API checks it but does not store it. The Job object has no metadata.
?output=inlineRemove itRead both forms of the output.
classifyRunId on splitsegments, after a /v2 classify jobclassifyRunId takes only a /v1 clr_ run id. A job_ id fails the job with invalid_request, and error.details.cause is classify_run_mismatch. Run classify with granularity: "page", then copy output.output.segments into segments.

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

/v1 run fieldJob fieldNote
object, for example extract_runobject is job, and capability is extract
id, for example exr_…id, for example job_…
statusstatusRead the status table below.
statusUrlThe Location header of a 202
outputoutput.outputRead the output of a job.
files, fileoutput.files, output.fileOn the durable path only.
errorerrorA processing_failed error has the /v1 code in error.details.cause.
usageusage{ credits, units }. Null while the job runs.
createdAt (on a list)created_at, completed_atJob fields use snake case.
/v1 statusJob status
queuedqueued
processingrunning
processedsucceeded
needs_inputneeds_input
failedfailed
cancelledcancelled
expiredexpired

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.

Item/v1/v2
Headerx-rk1-signaturex-cr-signature
AlgorithmES256RS256
Public keyshttps://api.cloudraker.com/v1/webhooks/jwks.jsonhttps://{slug}.cloudraker.run/.well-known/jwks.json
issrakerone-processhttps://{slug}.cloudraker.run
audNot presentThe exact URL of the endpoint
Delivery ideventIdjti
Job referenceprocessingIdjob_id
Event typetypetype
Body hashbodySha256, base64urlbody_sha256, 64 lowercase hex characters

Use jti to drop a delivery that you already processed.

The body also changes. data.job is the Job object.

Map the events

/v1 event/v2 event
run.completedjob.succeeded
run.failedjob.failed
processing.completedjob.succeeded or job.failed
processing.expiredjob.expired
processing.started, file.processed, file.failedNo event. Use a stream for progress.
No eventjob.needs_input, job.cancelled
agent_run.*, space.expired, work session eventsNo event. These events stay on /v1.

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.

Rule/v1/v2
Same key, same bodyThe first runThe first job
Same key, other bodyThe first run409 idempotency_key_reused
Scope of a keyThe organizationThe credential
Replay headeridempotent-replay: trueidempotent-replayed: true

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.

Cause/v1/v2
No credential401 unauthorized401 missing_credential
A bad credential401 invalid_token401 invalid_api_key or 401 invalid_token
No permission403 forbidden403 insufficient_scope
Too many requests429 rate_limited429 rate_limit_exceeded or 429 concurrency_limited
No credits402 credits_exhausted402 credits_exhausted
Unknown run or job404 not_found404 job_not_found

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.