Sync and async

Sync and async requests watermark files the same way. They use the same checks and cost the same credits. The only difference is how your app gets the result.

Choose an endpoint

Sync detection of images and PDFs always returns JSON directly. It never turns into a pending job. Upload, checking and download time add to processing time. An async request still waits until the upload is checked and stored.

Watermark a file synchronously

curl --fail-with-body https://api.etchv.com/watermarks/documents \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H 'Idempotency-Key: document_delivery_001' \
  -F 'file=@document.pdf' \
  --form-string 'data={"delivery":"delivery_001"}' \
  -D response-headers.txt --output response-body

• 200: save the file with its Content-Disposition filename. Keep the watermark ID from X-Watermark-ID.
• 202: read the JSON receipt and fetch result_url later. Do not save this body as a media file.
• Error: the job can be refused for invalid input, a webhook or storage destination that is unknown, disabled or unverified, or too few credits.

SDK embed methods wait for pending jobs for you.

Watermark a file asynchronously

Use /watermarks/documents/async with the same headers and fields. The response is a receipt. Save its request_id, status_url and result_url.

{
  "request_id": "req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "status": "queued",
  "operation": "embed",
  "format": "PDF",
  "frame_count": 2,
  "credits": 2,
  "attempts": 0,
  "webhook_id": null,
  "asset_id": null,
  "source_asset_id": null,
  "status_url": "/watermarks/jobs/req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "result_url": "/watermarks/jobs/req_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/result",
  "error_code": null,
  "result_expires_at": null
}

Retrieve a pending result (either mode)

1. GET status_url with your API key. Wait as long as Retry-After says: 6 seconds on Trial/Launch, 2 seconds on other plans.
2. If the status is queued, running or retrying, keep waiting.
3. On succeeded, GET result_url. Embedding returns the media file; detection returns JSON.
4. On failed, record request_id and error_code. Credits held for the job are refunded.

A detection can succeed and still report watermarked: false, meaning no watermark was found.

Receive an async webhook instead of polling

Create an enabled webhook endpoint and save its signing secret. Then pass the endpoint’s webhook_id in the async request:

curl "https://api.etchv.com/watermarks/images/async?webhook_id=$ETCHV_WEBHOOK_ID" \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H 'Idempotency-Key: image_delivery_001' \
  -F 'file=@image.png' \
  --form-string 'data={"delivery":"delivery_001"}'

Only the endpoint you select gets this job’s final event. Webhooks are optional.

Retry safely

An idempotency key is a value you choose and send in the Idempotency-Key header. If a request is sent twice with the same key and the same inputs, Etchv runs it only once. The retry gets the first job back instead of a second job and a second charge. The same key with different inputs returns 409.

Save your key before you upload. It must be 8–128 letters, digits, hyphens or underscores. An accepted job keeps running if you disconnect. Retries and result downloads do not add a charge or send another webhook event. To get an event again, ask for a webhook redelivery.

Try either mode in the dashboard

In Watermark media or Detect watermark, select Request mode. Sync waits for pending jobs for you. Async shows a receipt. Use Check result later or select a webhook. The copyable code examples match the mode you choose.

SDKs

Regular methods wait for the result. Submit methods return a receipt right away and do not poll.

In C#, Async in a method name means the call does not block your thread. Submit is what starts a background job on the server.

Choose where results are stored

Embedding accepts the storage_destination_id query and an optional storage_key query. Delivery retries reuse the already checked file and do not add a charge. Storage options.