Sume API headers: auth, idempotency, If-Match, rate limits

To call the Sume API, send your key in Authorization: Bearer or x-api-key (never both), Content-Type: application/json on JSON bodies, Idempotency-Key on creates, and If-Match on Format package writes. Every response carries x-sume-request-id, API responses can include ratelimit-* headers, and webhooks arrive signed with three x-sume-webhook-* headers.

The headers below come from Sume's Authentication, Errors and spend, Editing a Format package, and Webhooks docs and the live OpenAPI reference, read on 2026-09-27. Rate-limit budgets are explained in Sume API errors and rate limits; this page is the one-table header index.

Which headers does the Sume API use?

Each row links the post that explains that header in depth. The request after the table sends the three request headers a create needs; -D - makes curl print the response headers too, including x-sume-request-id and any rate-limit headers.

curl -sS -D - -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{"input": {"product_url": "https://example.com/p/8823"}}'

Which header should carry my API key?

Either one, used consistently, but never both: a request carrying both fails 401 unauthorized with Send only one API key credential., as How Sume API keys work explains along with the gateway trap that causes it.

• The TypeScript SDK sends x-api-key only, and the CLI defaults to x-api-key.
• Hosted MCP accepts either header when you connect with an API key instead of OAuth.
• Six public routes need no key: GET /v1/health, GET /v1/catalog, GET /v1/openapi.json, GET /v1/bgm/catalog, GET /v1/bgm/categories, and POST /v1/bgm/pick.
• The key is the actor: Sume resolves workspace and owner from it, so keep workspace_id, owner_user_id, and user_id out of request bodies.
• Keys stay on servers. Never put one in frontend JavaScript or a mobile app.

How do Idempotency-Key and If-Match differ?

Idempotency-Key makes a create safe to retry: the same key and body return the original job or run, a different body is 409 idempotency_conflict, and on Format runs and bulk queues the header wins over a body idempotency_key. Idempotency keys for AI video APIs covers key design.

If-Match guards an edit instead: it carries the Format's package_sha, a bare 40-character hex string rather than an opaque ETag, and a stale value is 409 format_package_sha_mismatch with the current sha in error.details.package_sha. See Optimistic concurrency with If-Match.

What comes back on a response?

x-sume-request-id is the Sume request id, the same value as error.request_id in an error body. It is separate from a generation job's request_id, so quote both to support. Keep it in your logs, and redact API keys and signed URLs from the same logs.

The rate-limit headers describe whichever budget, read or write, the request spent from; Sume API errors and rate limits lists the budgets per plan.

How do I verify the webhook headers?

Sume signs the raw body with HMAC SHA-256 over <timestamp>.<raw_body>, using the timestamp header's value. Five minutes is a reasonable replay window for that timestamp.

• Split x-sume-webhook-signature on commas and accept the delivery when any sume-v1= entry matches. During a secret rotation it carries one entry per live secret, newest first, so comparing the whole header fails.
• Compare x-sume-webhook-secret-fingerprint with the fingerprint shown beside your secret in the dashboard. During a rotation it names the new secret.
• Job and run webhooks share this scheme and one signing secret, so one verifier covers both.