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

# API reference

> Base URL, authentication, conventions and every endpoint of the Avina Data API.

The Avina Data API is a REST API. Requests and responses are JSON. You authenticate by sending an API key in the `Authorization` header, and every error has the same shape.

> [card] Base URL
>
> `https://api.avina.io/v1`

> [card] Authentication
>
> `Authorization: Bearer <api key>`

## Make your first request

`GET /me` checks a key and returns its workspace. It is free.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.avina.io/v1/me \
  -H "Authorization: Bearer $AVINA_API_KEY"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os, requests

response = requests.get(
    "https://api.avina.io/v1/me",
    headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"},
)
print(response.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://api.avina.io/v1/me", {
  headers: { Authorization: `Bearer ${process.env.AVINA_API_KEY}` },
});
console.log(await response.json());
```

New to the API? The [quickstart](https://docs.data.avina.io/quickstart.md) takes you from a key to verified results.

## Authentication

The Data API is in beta. [Request access](https://docs.data.avina.io/get-access.md) if your workspace does not have it yet.

Every request needs a workspace API key in the `Authorization` header. Workspace admins create and revoke keys in the [Avina dashboard](https://app.avina.io/settings/api-keys) under **Settings → API Keys**. A key is shown once, when it is created.

* A key acts for its whole workspace. It can start searches that spend the workspace's credits.
* The key decides the workspace. No header or parameter can select a different one.
* After a key is revoked, it can keep working for up to 60 seconds.

> [!WARNING]
>
> Keep API keys on your servers. Do not put them in browser code, mobile apps or public repositories. If a key leaks, revoke it in the dashboard and create a new one.

## Endpoints

> [accordion] Companies
>
> | Method | Path | |
> | - | - | - |
> | `POST` | [`/companies/search`](https://docs.data.avina.io/api-reference/companies/search) | Start a company search |
> | `GET` | [`/companies/search/{search_id}/status`](https://docs.data.avina.io/api-reference/companies/get-search) | Get status, progress and spend |
> | `GET` | [`/companies/search/{search_id}/results`](https://docs.data.avina.io/api-reference/companies/list-results) | List the companies found |
> | `POST` | [`/companies/search/{search_id}/cancel`](https://docs.data.avina.io/api-reference/companies/cancel-search) | Stop a search |

> [accordion] People
>
> | Method | Path | |
> | - | - | - |
> | `POST` | [`/people/search`](https://docs.data.avina.io/api-reference/people/search) | Start a people search |
> | `GET` | [`/people/search/{search_id}/status`](https://docs.data.avina.io/api-reference/people/get-search) | Get status, progress and spend |
> | `GET` | [`/people/search/{search_id}/results`](https://docs.data.avina.io/api-reference/people/list-results) | List the people found |
> | `POST` | [`/people/search/{search_id}/cancel`](https://docs.data.avina.io/api-reference/people/cancel-search) | Stop a search |

> [accordion] Parse
>
> | Method | Path | |
> | - | - | - |
> | `POST` | [`/companies/search/parse`](https://docs.data.avina.io/api-reference/parse/companies) | Turn text into a company search request |
> | `POST` | [`/people/search/parse`](https://docs.data.avina.io/api-reference/parse/people) | Turn text into a people search request |

> [accordion] Personas
>
> | Method | Path | |
> | - | - | - |
> | `GET` | [`/personas`](https://docs.data.avina.io/api-reference/personas/list) | List personas |
> | `POST` | [`/personas`](https://docs.data.avina.io/api-reference/personas/create) | Create a persona |
> | `GET` | [`/personas/{persona_id}`](https://docs.data.avina.io/api-reference/personas/get) | Get a persona |
> | `PATCH` | [`/personas/{persona_id}`](https://docs.data.avina.io/api-reference/personas/update) | Update a persona |
> | `DELETE` | [`/personas/{persona_id}`](https://docs.data.avina.io/api-reference/personas/delete) | Delete a persona |

> [accordion] Account
>
> | Method | Path | |
> | - | - | - |
> | `GET` | [`/me`](https://docs.data.avina.io/api-reference/account/me) | Check a key and get its workspace |
> | `GET` | [`/usage`](https://docs.data.avina.io/api-reference/account/usage) | Get the credit balance and usage |

> [accordion] Coming Soon
>
> [Monitor](https://docs.data.avina.io/api-reference/monitor.md), [Enrich](https://docs.data.avina.io/api-reference/enrich.md) and [Ask](https://docs.data.avina.io/api-reference/ask.md) are not available yet.

## Conventions

| | |
| - | - |
| **Format** | JSON request and response bodies. Send `Content-Type: application/json`. Field names are `snake_case`. |
| **Objects** | Every top-level object has an `object` field naming its type: `company_search`, `company_search_result`, `company_search_parse`, `people_search`, `person_search_result`, `people_search_parse`, `persona`, `api_key`, `usage`, `list`. |
| **Timestamps** | UTC, ISO 8601: `2026-11-12T17:02:11Z`. |
| **IDs** | Strings. Store and send them back unchanged; do not parse them. |
| **Money** | Credits are numbers. 1 credit = \$1.00. Company financials are in US dollars. |
| **Unknown values** | `null`. A value that is not known is never estimated or made up. |
| **Strict bodies** | A field the endpoint does not recognize returns `400 invalid_request` rather than being ignored. |
| **Body size** | Request bodies are limited to 100 KB. |

## Asynchronous searches

Searches run in the background. A `POST` that starts one returns `202 Accepted` with the search's `id` before any results exist.

**1. Start**

`POST /companies/search` or `POST /people/search` returns `202` and an `id`.

**2. Poll**

`GET .../status` until `status` is `completed`, `failed` or `cancelled`.

**3. Read**

`GET .../results`, following `next_cursor`, until `has_more` is `false`.

See [Search lifecycle](https://docs.data.avina.io/concepts/search-lifecycle.md) and [Poll and paginate](https://docs.data.avina.io/guides/poll-and-paginate.md).

## Pagination

Search results are returned in pages. Each page gives you a cursor, a marker for your position, which you send back to get the next page.

| Parameter | Meaning |
| - | - |
| `limit` | Page size, 1 to 100. Default 25. |
| `after` | The `next_cursor` from the previous page. Omit on the first call. |

A page has `data`, `has_more` and `next_cursor`. For search results, `next_cursor` is always returned, even on an empty page, so you can come back for results found later.

## Idempotency

`POST` requests that create something (starting a search, creating a persona, and Parse) accept an `Idempotency-Key` header: any unique string of 1 to 255 characters. Retrying with the same key and the same body within 24 hours returns the original response, marked with `Idempotent-Replayed: true`, instead of doing the work again.

Always send one when you start a search. Without it, a retried request starts, and charges for, a second search. See [Errors and retries](https://docs.data.avina.io/guides/errors-and-retries.md).

## Rate limits

Each API key can make **120 requests per minute**. Responses carry these headers:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | Requests allowed per window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Seconds until the window resets |

Over the limit, requests get `429 rate_limited` with a `Retry-After` header. There is no limit on how many searches a workspace can run at the same time.

## Request IDs

Every response has an `X-Request-Id` header, such as `req_8f2a61c09d4e7b3a5f10c2d8`. Error bodies repeat it as `request_id`. Include it when you contact support.

## Errors

Errors use one shape, with a stable `code` to branch on:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 500",
    "request_id": "req_8f2a61c09d4e7b3a5f10c2d8",
    "details": [{ "field": "limit", "message": "must be between 1 and 500" }]
  }
}
```

The [errors reference](https://docs.data.avina.io/api-reference/errors.md) lists every code.

## Credits

Starting a search spends credits as results are found. Everything else in this reference is free: reading status and results, parsing, cancelling, and managing personas. One credit is one US dollar. See [Pricing](https://docs.data.avina.io/concepts/pricing.md).

## OpenAPI

The full contract is available as an [OpenAPI 3.1 specification](https://docs.data.avina.io/api-reference/openapi.md).


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