Introduction

Authentication

Databar uses API keys to allow access to the API. Include your key in the x-apikey header on every request.

curl https://api.databar.ai/v1/user/me \
  -H "x-apikey: YOUR_API_KEY"

To find your API key, head over to your Databar workspace and click Integrations.

Base URL

All API requests should be made to:

https://api.databar.ai

Async Pattern

Some operations (bulk enrichments, waterfalls) run asynchronously. The flow is:

Submit the request

Call a run or bulk-run endpoint. You’ll receive a task_id in the response.

Poll for results

Call GET /v1/tasks/{task_id} with the task_id. The status field will be processing, completed, partially_completed or failed. For a bulk run the response also carries progress with per-input counts, so you can see it advancing. A task you no longer want can be stopped with POST /v1/tasks/{task_id}/cancel.

Retrieve your data

When status is completed, the data field contains your results. For bulk runs, data is aligned to your inputs: one element per input, in the same order you submitted them, with null for inputs that returned no data (so len(data) equals the number of inputs and data[i] is the result for input i). A single (non-bulk) run returns the result object directly.

Data from enrichment and waterfall tasks is stored for 24 hours. After that, the data is permanently deleted and the task status will return gone. Make sure to retrieve your results promptly.

Pagination

The GET /v1/table/{table_uuid}/rows endpoint supports pagination:

Parameter	Default	Description
`per_page`	1000	Number of rows to return per page.
`page`	1	Page number to retrieve.

The response includes has_next_page and total_count to help you iterate.

Error Handling

The API uses standard HTTP status codes. All error responses return a JSON body with a detail field describing the issue.

Common Error Codes

Code	Meaning	When it happens
`400`	Bad Request	Invalid or missing parameters in your request. The response body shows which fields failed validation.
`403`	Forbidden	Your API key is missing, invalid, or doesn’t have access to the requested resource.
`404`	Not Found	The enrichment, waterfall, table, or task ID you referenced doesn’t exist.
`406`	Insufficient Credits	Your account doesn’t have enough credits or your plan doesn’t support this operation.
`409`	Conflict	The resource changed since you read it — an `internal_version` token is stale — or the action is blocked by something still using the resource, such as a table column that runs the flow you are deleting.
`410`	Gone	The requested data has expired. Task results are deleted after 24 hours.
`422`	Validation Error	The request body failed schema validation. The response includes field-level error details.

Error Response Formats

Bad input (400 and 422) uses one envelope. error is a stable code, detail is a string you can show to a person. Extra keys depend on the code. Parameter validation (400):

{
  "error": "INVALID_PARAMS",
  "detail": "Row 1: domain: This field is required.",
  "rows": [
    {"position": 1, "fields": {"domain": ["This field is required."]}}
  ]
}

Row insert / update / upsert (400):

{
  "error": "UNKNOWN_COLUMNS",
  "detail": "Unknown columns: fake1. Available: email, name.",
  "columns": ["fake1"],
  "available_columns": ["email", "name"]
}

Row error codes: BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA, INVALID_FILTER, INVALID_PAGINATION, DUPLICATE_KEYS, PER_PAGE_TOO_LARGE. Schema validation (422) — the JSON does not match the endpoint’s body:

{
  "error": "VALIDATION_ERROR",
  "detail": "body.params: Field required",
  "fields": [{"loc": ["body", "params"], "msg": "Field required"}]
}

Insufficient credits (406):

{
  "detail": "Check the number of remaining credits or the tariff plan."
}

Getting Started

Overview

SDKs

Workspace

Workbooks

Tables

Headless

User

Authentication

Base URL

Async Pattern

Error Handling

Common Error Codes

Error Response Formats

​Authentication

​Base URL

​Async Pattern

​Pagination

​Error Handling

​Common Error Codes

​Error Response Formats

Authentication

Base URL

Async Pattern

Pagination

Error Handling

Common Error Codes

Error Response Formats