Go SDK

etchv.New(key, etchv.WithBaseURL(url), etchv.WithTimeout(d), etchv.WithHTTPClient(c))

The default timeout is 120 seconds. Every call takes a context, so you can cancel it. Set Options.Filename and Options.IdempotencyKey on each media request. The examples below assume you already have a client and ctx.

Errors have the type *etchv.Error. Each one has StatusCode, Detail, RequestID and IdempotencyKey. For jobs, it also has JobStatus and ErrorCode when they are available. Status 0 means a network failure, a cancellation or a client deadline. errors.Is(err, context.DeadlineExceeded) works.

var apiErr *etchv.Error
if errors.As(err, &apiErr) {
    log.Printf("HTTP %d, request %s: %s", apiErr.StatusCode, apiErr.RequestID, apiErr.Detail)
}

See HTTP errors and retry behavior. When you report a failure, include the request ID.

page, err := client.ListAssets(ctx, etchv.AssetListOptions{Kind: "watermarked", Limit: 25})
if err != nil { return err }
for _, item := range page.Items {
    asset, err := client.GetAsset(ctx, item.ID)
    if err != nil { return err }
    _, err = client.UpdateAsset(ctx, asset.ID, etchv.AssetUpdate{
        Version: asset.Version, Metadata: map[string]any{"campaign": "spring"},
    })
    if err != nil { return err }
}
// Continue with AssetListOptions{Cursor: *page.NextCursor} and the same filters until nil.
file, err := client.DownloadAsset(ctx, assetID) // file.Bytes, file.ContentType, file.Filename

An edit replaces the metadata and must send the asset's current version. A 409 conflict means the asset changed since you read it, so fetch it again and redo your edit. DeleteAsset deletes one asset. DeleteAssets deletes 1–50 assets as one action: either all are deleted or none are. Asset fields, filters and retention.

Read the file into memory before you submit it.

job, err := client.SubmitEmbed(ctx, etchv.MediaDocuments, pdfBytes,
    map[string]any{"delivery": "delivery_001"},
    etchv.Options{Filename: "document.pdf", IdempotencyKey: "delivery_001", WebhookID: webhookID})
if err != nil { return err }
status, err := client.GetEmbedJob(ctx, job.RequestID)
if err != nil { return err }
if status.Status == "succeeded" {
    result, err := client.GetEmbedResult(ctx, job.RequestID)
    // ...
}

The webhook is optional. In Java or Rust, pass null or None to skip it. Save the receipt. Job handling.

Methods: CreateWebhook, ListWebhooks, UpdateWebhook, DeleteWebhook, ListWebhookDeliveries, RedeliverWebhook. Viewing webhooks needs webhooks:read. Managing them needs webhooks:write and the owner or admin role. The signing secret is shown only once, so save it.

body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil { http.Error(w, "bad request", 400); return }
event, err := etchv.VerifyWebhook(body, r.Header, os.Getenv("ETCHV_WEBHOOK_SECRET"))
if err != nil { http.Error(w, "invalid signature", 400); return }
// Deduplicate on event.ID, enqueue work, then return 2xx.

VerifyWebhook checks the signature and timestamp. It also checks that the event ID in the body matches the header. Pass the raw request bytes and use a 300-second timestamp tolerance. Then skip events you already handled, queue the work and return 2xx. Verification rules.

job, err := client.SubmitEmbed(ctx, etchv.MediaDocuments, pdfBytes,
    map[string]any{"recipient": "customer-123"}, etchv.Options{
        Filename: "report.pdf", IdempotencyKey: "report-export-001",
        StorageDestinationID: destinationID, StorageKey: "reports/watermarked.pdf",
    })
if err != nil { return err }
// After the watermark job reports succeeded:
delivery, err := client.GetStorageDelivery(ctx, *job.StorageDeliveryID)

After the job succeeds, check the delivery with the storage:read scope. Checking before then returns 404. When the status is stored, download the file with DownloadStorageDelivery.

RetryStorageDelivery retries a failed or cancelled delivery at no cost. It needs storage:write and the owner or admin role. To manage destinations and deliveries, use CreateStorageDestination, VerifyStorageDestination, UpdateStorageDestination, DeleteStorageDestination, CreateStorageDelivery. See delivery recovery.