Traceable links

Share one file from your asset library with a traceable link. Each recipient confirms their email and downloads their own copy, watermarked with the link and their address. If a copy turns up somewhere it shouldn't, detection names the recipient it was made for.

Recipients

Up to 100 per link

Expiry

Up to 30 days by default · up to 1 year

Credits

One embed per copy

How a link works

You create a link from a source asset, the original of a file you have watermarked or uploaded, and send its url to your recipients yourself. Etchv does not send the link to your recipients.

A recipient opens the url, enters their email and types the 8-digit code Etchv sends to it. Only then can they download their copy. The page gives the same answers for every address, so it never tells anyone who the link was shared with.

Each copy is an ordinary embed of the source with this data:

{"link_id": "lnk_5d0c2b7e9a4f4e1c8b3a6d2f0e9c7a51", "recipient": "alex@example.com"}

It is saved in your asset library with the same pair as its metadata and the source as its parent.

A link names who may open it in one of two ways:

Use a key with links:write to create and revoke links, and links:read to read them. In the dashboard, open an original in Assets and choose Share traceable copies.

Create a link

curl --fail-with-body https://api.etchv.com/links \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H 'Idempotency-Key: board-pack-2026-10' \
  -H 'Content-Type: application/json' \
  -d '{
    "asset_id": "'"$SOURCE_ASSET_ID"'",
    "name": "Board pack, October",
    "recipients": ["alex@example.com", "sam@example.com"]
  }'

The response is 201 with the link. Etchv first checks that your workspace has the credits for every listed recipient's copy, or for one copy for a domain link. If not, it returns 402, and no link exists. Its detail has code insufficient_credits, estimated_credits and available_credits.

An Idempotency-Key of 8 to 128 letters, digits, hyphens or underscores is optional. A retry with the same key and body returns the same link with 200; the same key with a different body returns 409.

Estimate the credits

Takes the same body as creating a link, runs the same checks and creates nothing. Use it to show the cost before you create the link.

{
  "asset_id": "ast_…",
  "media_type": "document",
  "prepare": "on_open",
  "credits_per_copy": 4,
  "estimated_credits": 8,
  "available_credits": 1850,
  "enough_credits": true,
  "latest_expires_at": "2027-10-20T09:15:00+00:00"
}

estimated_credits is null for a domain link, because nobody knows yet how many people will open it. latest_expires_at is the latest expires_at this link could have.

When copies are made

An on_open copy is made while the recipient waits on the page. If it isn't ready right away, Etchv also emails the recipient when it is. Long files default to on_create, so their copies are made in advance. batch_id names the batch making them.

A copy costs the same credits as embedding the source yourself, at credits_per_copy, and is charged only when it is made. A copy that fails is refunded. A recipient who never opens an on_open link costs nothing.

An on_create link's batch holds its copies' credits when the link is created. An on_open link's check holds nothing: each copy needs credits when its recipient opens the link, and a domain link is checked for one copy only, so keep enough credits until your recipients have opened it. While the workspace has too few, a recipient who opens the link gets no copy.

Read a link

{
  "id": "lnk_5d0c2b7e9a4f4e1c8b3a6d2f0e9c7a51",
  "url": "https://etchv.com/l/Yp3kQ8vN2rT6wX1zA4bC7d",
  "name": "Board pack, October",
  "asset_id": "ast_…",
  "media_type": "document",
  "status": "active",
  "prepare": "on_open",
  "allowed_domains": [],
  "expires_at": "2026-11-26T14:02:00+00:00",
  "download_limit": null,
  "recipient_count": 2,
  "credits_per_copy": 4,
  "estimated_credits": 8,
  "batch_id": null,
  "webhook_id": null,
  "created_at": "2026-10-27T14:02:00+00:00",
  "revoked_at": null,
  "recipients": [
    {
      "email": "alex@example.com",
      "status": "opened",
      "opened_at": "2026-10-27T15:10:41+00:00",
      "last_opened_at": "2026-10-27T15:10:41+00:00",
      "open_count": 1,
      "download_count": 1,
      "copy": {"status": "ready", "asset_id": "ast_…", "error_code": null}
    },
    {
      "email": "sam@example.com",
      "status": "not_opened",
      "opened_at": null,
      "last_opened_at": null,
      "open_count": 0,
      "download_count": 0,
      "copy": {"status": "not_started", "asset_id": null, "error_code": null}
    }
  ]
}

List links

Newest first, without recipients. limit is 1 to 50 (default 20). Pass next_cursor from one page as before to get the next; it is null on the last page. A before that names no link of yours returns 404.

curl --fail-with-body "https://api.etchv.com/links?limit=20" \
  -H "X-API-Key: $ETCHV_API_KEY"

List opens and downloads

Newest first, with limit 1 to 100 (default 50). Pass next_cursor as before for the next page; an unknown before returns 400.

Revoke a link

curl --fail-with-body -X POST "https://api.etchv.com/links/$LINK_ID/revoke" \
  -H "X-API-Key: $ETCHV_API_KEY"

New opens and downloads stop at once. on_create copies that haven't been queued yet are canceled and not charged; copies already queued finish. Copies already downloaded keep their watermark. Revoking again returns the link.

Webhook events

Give webhook_id when creating a link to receive its events at a webhook endpoint, signed and retried like job events.

{
  "id": "evt_…",
  "type": "link.opened",
  "api_version": "2026-09-12",
  "created_at": "2026-10-27T15:10:41+00:00",
  "data": {
    "link_id": "lnk_5d0c2b7e9a4f4e1c8b3a6d2f0e9c7a51",
    "name": "Board pack, October",
    "asset_id": "ast_…",
    "recipient": "alex@example.com",
    "opened_at": "2026-10-27T15:10:41+00:00",
    "first_open": true,
    "verified_by": "email_code"
  }
}

For link.locked, data has link_id, name, asset_id, locked_until and reason too_many_wrong_codes.

Find who a copy was made for

Detect the file with a key that has watermarks:detect and links:read. When the watermark is on one of your links' copies, the response's copy names the link, the recipient and when they first opened it.