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.

Setup

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

JSON requests

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_code": "US"
  }' | jq

Do not infer response casing or optionality from a request example. Generate types from OpenAPI or validate responses against its schemas.

Idempotent mutations

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.

Asynchronous work

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. Do not poll continuously or assume a fixed completion time. See Common patterns for an example.

Lists and filters

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

Use cursor pagination when a list response indicates that more rows are available. See Pagination.

Errors

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.