API quickstart

Create a key

Sign in at /workbench?view=api&signin=1, name the agent, set its per-run and daily credit ceilings, and create a key. Copy it once and store it as an application secret. Keys expire after 30 days and can be rotated or revoked.

Set DATAWEBOT_BASE_URL to https://www.datawebot.com in production. Local development uses http://localhost:3000.

Estimate first

POST the same input to /api/product/estimate to review the cost and balance. Set maxCredits to the task's authorized ceiling; adjust scope if necessary.

Submit once

In this sample, merchant.example is a reserved placeholder and cannot be submitted. Replace it only with a public URL you are authorized to use and the service currently supports.

A successful submission returns HTTP 202 and run.id. If the response is lost, repeat the same input and key. Changing inputs with an existing key returns 409.

curl "$DATAWEBOT_BASE_URL/api/product/runs" \
  -H "Authorization: Bearer $DATAWEBOT_API_KEY" \
  -H "Idempotency-Key: first-extraction-001" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example","operation":"catalogue","maxPages":2,"maxCredits":2,"paginationPages":1,"productPages":0,"categoryPages":0}'

Wait and retrieve

Poll only as frequently as next_poll_after permits. When Ready, retrieve results and follow next_cursor until null. Inspect action_required while Processing.

For Unavailable requests, read the explanation. Check completeness and warnings before using partial output.

curl "$DATAWEBOT_BASE_URL/api/product/runs/$RUN_ID" \
  -H "Authorization: Bearer $DATAWEBOT_API_KEY"

curl "$DATAWEBOT_BASE_URL/api/product/runs/$RUN_ID/results" \
  -H "Authorization: Bearer $DATAWEBOT_API_KEY"

Handle errors by code

Every error includes error.code, error.message, error.request_id and error.retryable. Validation errors can include fields. Rate limits include retry_after and the HTTP Retry-After header.

Never create a new idempotency key merely because a submission returned a retryable transport or server error. Recover the original identity first.