Authentication
Send an X-API-Key header with a scoped Etchv machine key. Image endpoints do not accept Clerk session tokens. Account administration uses Clerk session authentication separately.
POST /watermarks/images
Requires watermarks:embed. Submit multipart/form-data with the following fields:
| Field | Type | Meaning |
|---|---|---|
| file | Binary image | Maximum 20 MB and 40 megapixels. |
| data | JSON string | Non-empty object. Its canonical SHA-256 digest is embedded. |
Returns 200 image/png. The X-Watermark-ID response header contains the embedded identifier as a hexadecimal string. Save it with your record; the API does not retain the supplied payload as a searchable attribution record.
curl "$ETCHV_API_URL/watermarks/images" \
-H "X-API-Key: $ETCHV_API_KEY" \
-F 'file=@campaign.jpg' \
-F 'data={"asset":"campaign_01","recipient":"partner_42"}' \
-D response-headers.txt \
--output protected.png POST /watermarks/imagesimage/png
POST /watermarks/images/detect
Requires watermarks:detect. Submit the recovered image as multipart field file.
curl "$ETCHV_API_URL/watermarks/images/detect" \
-H "X-API-Key: $ETCHV_API_KEY" \
-F 'file=@recovered.png'| Response field | Meaning |
|---|---|
| watermarked | Boolean indicating a detected watermark. |
| confidence | Number from 0 to 1: mean certainty of decoded bits, not a calibrated attribution probability. |
| watermark_id | Recovered hexadecimal identifier, or null when no identifier is returned. |
Error handling
| Status | Recommended handling |
|---|---|
| 401 | Check missing, invalid, expired or revoked credentials. |
| 403 | Check key permissions and account or organization status. |
| 413 | Reduce the upload size or pixel dimensions. |
| 422 | Check image validity and the data JSON object. |
| 503 | Model unavailable. Retry with bounded backoff and handle continued failure. |
Use timeouts and check the HTTP status before treating a response as an image or a successful detection. Never log your API key.