Watermarked asset library API

Browse, download and organize your files in the asset library. Each successful embed creates two linked records: one for the original upload and one for the watermarked result. Detection does not create assets.

Files: Up to 1 year on Etchv*
Records: Until you delete them
Credits: Free to manage

While your subscription is active. 30 days on the free trial.

List assets

GET/assets

curl --get https://api.etchv.com/assets \
  -H "X-API-Key: $ETCHV_API_KEY" \
  --data-urlencode 'kind=watermarked' \
  --data-urlencode 'media_type=image' \
  --data-urlencode 'limit=25'

Query	Options
`limit`	1–100; default `25`
`cursor`	Previous response’s `next_cursor`
`kind`	`source` or `watermarked`; omit for both
`media_type`	`image`, `document` or `video`; omit for all
`watermark_id`	Exact 64-character hexadecimal watermark ID

limit

Options: 1–100; default 25

cursor

Options: Previous response’s next_cursor

kind

Options: source or watermarked; omit for both

media_type

Options: image, document or video; omit for all

watermark_id

Options: Exact 64-character hexadecimal watermark ID

Returns { "items": [...], "next_cursor": "..." }, newest first. Use the same filters and Organization for every page. Stop when next_cursor is null. The list leaves out metadata contents. Read a single record to get them.

Authentication

Send X-API-Key on every request, including downloads. A key can only reach assets in its own Organization.

Scope	Access
`assets:read`	List, read and download
`assets:write`	Rename and replace metadata
`assets:delete`	Delete; requires an owner or admin

assets:read

Access: List, read and download

assets:write

Access: Rename and replace metadata

assets:delete

Access: Delete; requires an owner or admin

Scopes are the permissions a key has. Existing keys do not gain new scopes automatically. In the dashboard, members can browse and edit. Owners and admins can also delete.

Read a record

GET/assets/{asset_id}

curl "https://api.etchv.com/assets/$ASSET_ID" \
  -H "X-API-Key: $ETCHV_API_KEY"

Field	Meaning
`id`, `name`, `version`	Permanent asset ID, editable name and edit version
`kind`, `parent_asset_id`	Source or output; an output points to its source
`media_type`, `format`, `content_type`	Media category, format and MIME type
`size_bytes`, `sha256`	Stored file size and checksum
`request_id`, `watermark_id`	Job that created it, and its watermark ID; empty for sources, since Etchv adds no watermark to them
`created_at`, `updated_at`, `file_expires_at`	UTC timestamps
`file_available`, `download_url`	Availability and authenticated download path
`metadata`	Your optional JSON record

id, name, version

Meaning: Permanent asset ID, editable name and edit version

kind, parent_asset_id

Meaning: Source or output; an output points to its source

media_type, format, content_type

Meaning: Media category, format and MIME type

size_bytes, sha256

Meaning: Stored file size and checksum

request_id, watermark_id

Meaning: Job that created it, and its watermark ID; empty for sources, since Etchv adds no watermark to them

created_at, updated_at, file_expires_at

Meaning: UTC timestamps

file_available, download_url

Meaning: Availability and authenticated download path

metadata

Meaning: Your optional JSON record

Set include_metadata=false to leave out metadata. Assets that are unknown, deleted or in another Organization return 404.

Download a file

GET/assets/{asset_id}/content

curl --fail-with-body "https://api.etchv.com/assets/$ASSET_ID/content" \
  -H "X-API-Key: $ETCHV_API_KEY" --output saved-file.png

Use your asset’s file extension. The response keeps its MIME type and includes a filename. Keep the API key on your server. A download URL alone gives no access.

Rename or update metadata

PATCH/assets/{asset_id}

curl --request PATCH "https://api.etchv.com/assets/$ASSET_ID" \
  -H "X-API-Key: $ETCHV_API_KEY" -H 'Content-Type: application/json' \
  --data '{"version":1,"name":"Spring campaign","metadata":{"campaign":"spring","recipient":"partner-42"}}'

Send the current version and at least one of name or metadata. Each successful edit adds one to the version. If you get 409, the record changed since you read it: reload it and apply your changes again.

Name and metadata limits

Field	Limit
Request body	64 KB; unknown fields rejected
Name	1–200 printable characters
Metadata	JSON object, 8 KB, up to eight nested levels
Metadata keys	1–100 characters; no dots, null characters or leading `$`
Numbers	Finite; integers must fit signed 64-bit values

Request body

Limit: 64 KB; unknown fields rejected

Name

Limit: 1–200 printable characters

Metadata

Limit: JSON object, 8 KB, up to eight nested levels

Metadata keys

Limit: 1–100 characters; no dots, null characters or leading $

Numbers

Limit: Finite; integers must fit signed 64-bit values

Files and records

Storage	Download window
Job result	24 hours
Etchv-hosted asset	1 year from completion while your subscription is active; 30 days on the free trial
Customer bucket	Your bucket’s retention policy
Asset record	Until deleted, even after the file expires

Job result

Download window: 24 hours

Etchv-hosted asset

Download window: 1 year from completion while your subscription is active; 30 days on the free trial

Customer bucket

Download window: Your bucket’s retention policy

Asset record

Download window: Until deleted, even after the file expires

If a subscription ends, its files stay for 30 more days, but never past their first year. Subscribe again in that time to restore the full year. file_expires_at always shows the file’s current expiry date, so read it instead of working one out.

Embedding responses include X-Asset-ID and X-Source-Asset-ID. Job status includes asset_id and source_asset_id. Replays create no extra assets or charges. Creating the asset, finishing the job and charging credits happen together, or not at all.

Customer storage and expired files

After an Etchv file expires, file_available is false and download_url is null.

Results kept in your own bucket include storage_provider, storage_destination_id, storage_delivery_id and storage_status. Once the status is stored, file_expires_at is null and the download endpoint reads from your bucket. Access is checked at download time, so a download can still fail if the object was removed or the connection was revoked.

staging_expires_at shows how long a delivery can be retried, up to 30 days. staging_deleted_at confirms that Etchv’s temporary copy of the output was removed. A failed delivery stays visible and can be retried. Meanwhile, its result stays on Etchv. Originals stay on Etchv under the retention rules above.

Connecting a bucket does not move existing files. Use Move to my storage on an available Etchv-hosted result. Each result has one destination. See storage.

Delete assets

DELETE/assets/{asset_id}

curl --request DELETE "https://api.etchv.com/assets/$ASSET_ID" \
  -H "X-API-Key: $ETCHV_API_KEY"

To delete several at once, send 1–50 asset IDs to POST /assets/bulk-delete:

{ "asset_ids": ["SOURCE_ASSET_ID", "OUTPUT_ASSET_ID"] }

Returns 204. A batch either succeeds completely or changes nothing. Asset IDs that are unknown or in another Organization return 404. Deleting your own asset again is safe.

What deletion removes

New reads and downloads stop at once. Etchv keeps trying to remove the file in the background. A download already in progress may finish.
Source and output are separate. Select both to delete both.
Deleting an output also blocks its job result and any replay of the request. Both return 410, without another charge.
Names and custom metadata are cleared. A minimal set of cleanup, job and billing records remains.
Copies already downloaded elsewhere keep their watermarks. Etchv does not delete objects in your own bucket.

SDKs

All six SDKs support listing, downloads, version-checked edits and deletion of assets. Embedding results include both asset IDs.

View source on GitHub

Asset library

List assets

Authentication

Read a record

Download a file

Rename or update metadata

Files and records

Delete assets

SDKs

Your privacy, your choice

Privacy preferences

Essential

Analytics