Making requests

Use the generated OpenAPI document to select a route and inspect its authoritative request and response schema. This page documents conventions that apply across API groups.

SetupCopy Anchor Link

export EXTRALT_API_KEY="your-api-key"
export EXTRALT_EXTRACT_URL="https://api.extralt.com/v1/extract"

JSON requestsCopy Anchor Link

Send JSON request bodies with Content-Type: application/json. Request fields use snake_case.

curl -s -X POST "$EXTRALT_EXTRACT_URL/robots" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" \
  -H "Idempotency-Key: robot-create-example-1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-store.com/products/sample",
    "country": "US"
  }' | jq

Do not infer response casing or optionality from a request example. The SDKs type every request and response; other clients can generate types from OpenAPI or validate responses against its schemas.

Idempotent mutationsCopy Anchor Link

Robot, Run, Schedule, Import, and Enrichment creation, plus Run restart, require an Idempotency-Key header. Use a unique, stable key for one logical operation. If the connection fails, retry the same payload with the same key. Reusing that key with a different payload returns 409 Conflict.

Keys contain 1 to 255 visible ASCII characters. Do not recycle keys across unrelated operations. The SDKs generate a key for each call and reuse it for that call's retries.

Asynchronous workCopy Anchor Link

Robots, Runs, Imports, and Enrichments can be asynchronous. A create request returns the resource or job identifier; read the corresponding resource until it reaches a terminal state. Keep the identifier as lineage for later Captures or Items.

Use bounded polling with a delay, as the SDKs' wait() does. Do not poll continuously or assume a fixed completion time. See Common patterns for an example.

Lists and filtersCopy Anchor Link

List routes accept resource-specific filters. For example, Captures can be scoped to a Run, Robot, or Import. Prefer the narrowest server-side filter available instead of downloading an organization-wide result and filtering it locally.

curl -s "$EXTRALT_EXTRACT_URL/captures?run_id=$RUN_ID" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" | jq

The SDKs follow cursors while you iterate. Over HTTP, use cursor pagination when next_cursor is non-null; treat the cursor as opaque and keep the endpoint, filters, and sort unchanged. See Pagination.

ErrorsCopy Anchor Link

Check the HTTP status before reading a success payload. Treat 401 and 403 as authentication or organization-scope failures, 4xx validation errors as request problems, 429 as backpressure, and 5xx as retryable only when the operation is safe to retry. For mutations, retain the original Idempotency-Key. See Error handling.