> ## 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`, or `failed`.
  </Step>

  <Step title="Retrieve your data">
    When `status` is `completed`, the `data` field contains your results.
  </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.                  |
| `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

**Parameter validation error** (400):

```json theme={null}
{
  "detail": {
    "param1": ["This field is required."]
  }
}
```

**Batch operation error** (400) — for row insert/update/upsert:

```json theme={null}
{
  "error": "BATCH_TOO_LARGE",
  "max_size": 50
}
```

Batch error codes: `BATCH_TOO_LARGE`, `UNKNOWN_COLUMNS`, `INVALID_DATA`.

**Insufficient credits** (406):

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

**Schema validation error** (422):

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "params"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```