Bearer keys and scopes
Send Authorization: Bearer YOUR_API_KEY. The quickstart needs uploads.create, extractions.create, and extractions.read. Give a key only the scopes its integration needs and revoke it when it is no longer required.
Idempotent uploads and extraction creation
POST /uploads and POST /extractions require an Idempotency-Key containing 1 to 128 letters, digits, periods, underscores, colons, or hyphens. Store the key with the request payload before sending it. A retry with the same key and identical payload returns the original resource and Idempotent-Replay: true. A different payload using that key returns idempotency_conflict. Upload retries resume the same slot; completed uploads have no write URL and expired slots remain expired.
Request IDs and safe errors
Error envelopes contain a stable error code, safe message, and request_id. Keep that ID with your trace. Fix validation and authorization errors, wait after throttling, and poll durable extraction state after uncertain delivery.