datawebotDevelopers
API reference
Reference for the datawebot. Jobs REST API: authentication, endpoints, the Job request body, statuses, errors and limits.
Authentication and base URL
Base URL: https://api.datawebot.com. Send a dwb_ API key as Authorization: Bearer <key> on every request. Every response carries an X-Request-Id header. The machine-readable contract is /openapi.json.
The same operations are available as MCP tools (list_job_blueprints, submit_job, get_job, get_results) at https://mcp.datawebot.com/mcp.
Endpoints
| Method and path | Purpose |
|---|---|
| GET /v1/job-blueprints | Discover blueprints. q searches store, domain or operation; site filters by hostname; blueprint_id alone returns one contract. page_size up to 100 (default 30); follow next_cursor with the same filters |
| GET /v1/job-blueprints/search | Compact store search, or resolve a target URL to its store's blueprints, without fetching the source |
| POST /v1/jobs | Submit one URL as one Job. Requires Idempotency-Key |
| GET /v1/jobs | Your Jobs, newest first. page_size up to 100 (default 25) |
| GET /v1/jobs/{id} | Status, original request, credits and poll_after_seconds |
| GET /v1/jobs/{id}/results | A page of records. page_size up to 100; follow next_cursor |
| GET /v1/account | Credits available and held |
| GET /v1/usage | Jobs, results and credits charged this UTC month, by blueprint |
Job request body
| Field | Required | Meaning |
|---|---|---|
| blueprint_id | Yes | An ID returned by discovery; never construct one |
| url | Yes | The public URL to extract, up to 2,048 characters, matching the blueprint's input_schema |
| parameters | No | Blueprint-specific limits such as max_pages or max_products, within the blueprint's input_schema. Default is one page |
| blueprint_version | No | Always "1" |
Job statuses
| Status | Meaning |
|---|---|
| PENDING / INITIATED | Accepted or running. Poll after poll_after_seconds |
| COMPLETED | Finished; results are available |
| PARTIAL_COMPLETE | Finished with some pages missing; available results are returned and only fetched pages are charged |
| FAILED | Finished without results. Not charged |
| UNAVAILABLE | The blueprint is not accepting Jobs right now. Not charged |
Errors
| Code | HTTP | What to do |
|---|---|---|
| unauthorized | 401 | Check the key; it may be missing, expired or revoked |
| insufficient_credits | 402 | The balance can't cover the credit hold. Ask for fewer pages |
| not_found | 404 | No such Job for this account |
| idempotency_conflict | 409 | The key was used for a different request. Use a new key for a new Job |
| results_expired | 410 | Results were kept for seven days. Run a new Job |
| invalid_input / idempotency_key_required | 422 | Fix the request against the blueprint's input_schema |
| rate_limited / job_limit | 429 | Wait for Retry-After, or for active Jobs to finish |
| internal_error | 500 | Saved work is kept. Retry with the same Idempotency-Key |
Limits
- 20 submissions a minute and 20 active Jobs per account.
- Request bodies up to 8 KB, sent as application/json.
- Page limits come from each blueprint's input_schema and price (max_units).
- Results are kept for seven days after a Job finishes.
Need help? Contact support.