Idempotent requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, include an idempotency key. If a connection error occurs, you can safely repeat the request without the risk of creating a duplicate object or performing the update twice.

All POST requests accept idempotency keys. Don’t send idempotency keys in GET requests because it has no effect. These requests are idempotent by definition.

We save results only after the execution of an endpoint begins. If incoming parameters fail validation, or the request conflicts with another request that’s executing concurrently, we don’t save the idempotent result because no API endpoint initiates the execution. You can retry these requests.

Idempotent requests directly to the API:

When calling the API directly (for example, with curl), include an additional idempotency-key header:

curl -X POST 'http://127.0.0.1:10000/v1/work/ingest?view=full' \
     -H "Authorization: Bearer dl_3kwaw28Y6TGkFsLsd3QZqTbxvjha9CYav" \
     -H "Accept: application/json" \
     -H 'content-type: application/json' \
     -H "idempotency-key: jhdjseyguwyfeg" \
     -d '{"externalIdType":"medrxivId","id":"2025.08.20.25334101"}' 

It is recommended that you use a UUID-style key as your idempotency key. You can quickly generate one here.

Idempotent requests using the Drylab SDK

The SDK section later in this guide explains details, but in general, you can pass an idempotency key through the optional idempotencyKey?: string parameter in any method that calls a POST API endpoint.

If you don’t provide an idempotency key, the SDK will automatically generate one and re-use it behind the scenes if a retryable error occurs. The SDK-assigned idempotency key will be included in the idempotency-key header of the API response.