> ## Documentation Index
> Fetch the complete documentation index at: https://docs.databar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Databar.ai REST API reference

## Authentication

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

```bash theme={null}
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](https://databar.ai) 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:

<Steps>
  <Step title="Submit the request">
    Call a run or bulk-run endpoint. You'll receive a `task_id` in the response.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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):

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "detail": "body.params: Field required",
  "fields": [{"loc": ["body", "params"], "msg": "Field required"}]
}
```

**Insufficient credits** (406):

```json theme={null}
{
  "detail": "Check the number of remaining credits or the tariff plan."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.