Storage
Choose your storage
Choose where watermarked files are stored: included Etchv storage or your own Amazon S3, Google Cloud Storage or Azure bucket, plus retention and deletion.
Keep files on Etchv with no setup, or deliver watermarked results to your own cloud storage.
Choose a storage location
| Location | File retention |
|---|---|
| Etchv · default | Up to 1 year while your subscription is active; 30 days on the trial |
| Your S3, GCS or Azure destination | Your bucket’s lifecycle policy |
- Etchv · default
- File retention
- Up to 1 year while your subscription is active; 30 days on the trial
- Your S3, GCS or Azure destination
- File retention
- Your bucket’s lifecycle policy
Both appear in the asset library. Records stay until you delete them. Original uploads stay on Etchv, wherever the output goes.
If a subscription ends, Etchv keeps its files for 30 more days, but never past their first year. Subscribe again in that time to restore the full year. Each asset’s file_expires_at shows its current expiry date.
Connecting a bucket does not make it the default or move existing files. Choose it on each request, or use Move to my storage on an available Etchv-hosted result. Each result has one destination. You cannot move a result between your buckets or back to Etchv.
Connect your provider
Owners and admins can manage up to 10 destinations. Members can view them. Test connection writes and reads a small test file, .etchv-connection-dst_….txt, under your prefix (the folder path Etchv writes to). You may remove it afterward. Normal exports need neither delete nor bucket-list permissions.
Select storage on a request
curl -X POST \
"https://api.etchv.com/watermarks/documents/async?storage_destination_id=$DESTINATION_ID&storage_key=reports%2Fwatermarked.pdf&webhook_id=$WEBHOOK_ID" \
-H "X-API-Key: $ETCHV_API_KEY" \
-H "Idempotency-Key: invoice-storage-0001" \
-F 'file=@invoice.pdf' \
-F 'data={"recipient":"customer-123"}'| Option | Value |
|---|---|
storage_destination_id | Verified, enabled destination in your Organization; omit to use Etchv |
storage_key | Optional URL-encoded filename beneath the destination prefix |
webhook_id | Optional delivery notifications; async requests only |
storage_destination_id- Value
- Verified, enabled destination in your Organization; omit to use Etchv
storage_key- Value
- Optional URL-encoded filename beneath the destination prefix
webhook_id- Value
- Optional delivery notifications; async requests only
Storage options work on all sync and async embedding endpoints. Detection rejects them. If you change the destination or key but reuse the same idempotency key, you get 409.
Object names, formats and size limits
The default name is the output asset ID plus its usual file extension. Prefix etchv and key reports produce etchv.
- No empty path segments,
..traversal, leading slashes or control characters. - Combined prefix and key: at most 800 UTF-8 bytes.
- Verified output: at most 256 MiB.
- File bytes and MIME type stay the same. A filename extension does not convert formats.
Durable delivery to your bucket
- Verify: Etchv watermarks the file, checks the output and holds it in temporary storage.
- Deliver: A worker uploads those bytes. Retries add no watermarking charge.
- Clean up: After delivery, downloads read from your bucket. Etchv removes its temporary copy and the job-result object.
Until delivery, downloads may come from the temporary copy. Failed uploads stay visible under the chosen destination and can be retried for up to 30 days. Until one succeeds, the result stays on Etchv. staging_deleted_at confirms cleanup. Delivered assets have file_expires_at: null because your bucket controls how long files are kept.
Track and download a delivery
Find storage_delivery_id in the job receipt, status or asset record, or X-Storage-Delivery-ID in a successful binary response. You can read the delivery after the job succeeds. Earlier requests return 404.
curl "https://api.etchv.com/storage/deliveries/$DELIVERY_ID" \
-H "X-API-Key: $ETCHV_API_KEY"| Status | Meaning |
|---|---|
queued, uploading, retrying | Delivery in progress |
stored | Verified bytes delivered |
failed, cancelled | Inspect error_code before retrying |
queued,uploading,retrying- Meaning
- Delivery in progress
stored- Meaning
- Verified bytes delivered
failed,cancelled- Meaning
- Inspect
error_codebefore retrying
Records include the provider, object key, URI, attempts and recent history. Private destinations return s3:, gs: or azure: URIs. Destinations that are already public also return public_url. This setting never changes access policies.
Download with your provider credentials, or through Etchv’s proxy using your API key:
curl "https://api.etchv.com/storage/deliveries/$DELIVERY_ID/content" \
-H "X-API-Key: $ETCHV_API_KEY" -o watermarked.pdfDownload access and integrity
The proxy keeps working after the temporary copy is removed, as long as the asset record exists, the connection is enabled and verified, and the object can still be reached. It checks the downloaded bytes against the saved checksum. If the object has changed, the download does not complete.
Direct public URLs follow your bucket’s access policy and skip this check. Download links never expose cloud credentials or write-capable SAS tokens.
API management
| Scope | Access |
|---|---|
watermarks:embed | Select an existing verified destination when embedding |
storage:read | List destinations, inspect deliveries and download |
storage:write + owner/admin | Manage, verify, move assets and retry delivery |
watermarks:embed- Access
- Select an existing verified destination when embedding
storage:read- Access
- List destinations, inspect deliveries and download
storage:write+ owner/admin- Access
- Manage, verify, move assets and retry delivery
| Method | Path | Action |
|---|---|---|
| GET / POST | /storage | List / create |
| PATCH | /storage | Change enabled or replace credentials |
| DELETE | /storage | Disconnect and discard credentials |
| POST | /storage | Test write and read access |
| GET | /storage | List 50; pass next_cursor as after |
| POST | /storage | Move a result with {"asset_id":"ast_…","key":"optional |
| GET | /storage | Read status |
| POST | /storage | Retry a failed or cancelled upload |
| GET | /storage | Download stored bytes |
- GET / POST
- Path
/storage/destinations - Action
- List / create
- PATCH
- Path
/storage/destinations /{id} - Action
- Change
enabledor replacecredentials
- DELETE
- Path
/storage/destinations /{id} - Action
- Disconnect and discard credentials
- POST
- Path
/storage/destinations /{id} /verify - Action
- Test write and read access
- GET
- Path
/storage/destinations /{id} /deliveries - Action
- List 50; pass
next_cursorasafter
- POST
- Path
/storage/destinations /{id} /deliveries - Action
- Move a result with
{"asset_id":"ast_…","key":"optional/file. png"}
- GET
- Path
/storage/deliveries /{id} - Action
- Read status
- POST
- Path
/storage/deliveries /{id} /retry - Action
- Retry a failed or cancelled upload
- GET
- Path
/storage/deliveries /{id} /content - Action
- Download stored bytes
Connection changes and duplicate deliveries
Provider, bucket, prefix and visibility cannot be changed. Create a new destination instead. Replacing credentials clears verification, so test again. For S3, update your role’s trust policy directly. Responses never return credentials.
A result’s destination and delivery key are fixed. Repeating the same result, destination and key returns the existing delivery. Changing the destination or key returns 409. Conditional writes stop Etchv from overwriting an object with different bytes. If it is unclear whether an upload finished, a retry accepts an existing object only if its bytes match.
Retry, retention and deletion
Etchv makes up to 10 automatic attempts over about 22 hours. For up to 30 days, you can start up to 10 manual retry cycles with no extra watermarking charge.
| Error code | Check |
|---|---|
provider_unavailable | Credentials, permissions or provider availability |
object_key_conflict | Different bytes already exist at the selected key |
source_or_destination_unavailable | Expired/deleted source, disabled Organization, or missing/disabled/unverified destination |
export_too_large | Output exceeds 256 MiB |
verified_source_mismatch | The temporary copy failed its checksum check; export is cancelled |
provider_unavailable- Check
- Credentials, permissions or provider availability
object_key_conflict- Check
- Different bytes already exist at the selected key
source_or_destination_unavailable- Check
- Expired/deleted source, disabled Organization, or missing/disabled/unverified destination
export_too_large- Check
- Output exceeds 256 MiB
verified_source_mismatch- Check
- The temporary copy failed its checksum check; export is cancelled
Retry timing and deletion behavior
Automatic delays: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours and 8 hours. Each manual retry starts a new automatic cycle.
Deleting an asset stops future exports and proxy downloads. Deleting a connection stops new exports and destroys its credentials. Uploads already in progress may finish. Neither action deletes objects in your bucket. Delivery history stays in Etchv.
SDKs
All six SDKs support destination and object-key options, async embedding and delivery status.