API reference - 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.

Base URL

https://api.avina.io/v1

Authentication

Authorization: Bearer <api key>

Make your first request

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

curl https://api.avina.io/v1/me \
  -H "Authorization: Bearer $AVINA_API_KEY"

import os, requests

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

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 takes you from a key to verified results.

Authentication

The Data API is in beta. Request access 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 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.

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

Companies

Method	Path
`POST`	`/companies/search`	Start a company search
`GET`	`/companies/search/{search_id}/status`	Get status, progress and spend
`GET`	`/companies/search/{search_id}/results`	List the companies found
`POST`	`/companies/search/{search_id}/cancel`	Stop a search

People

Method	Path
`POST`	`/people/search`	Start a people search
`GET`	`/people/search/{search_id}/status`	Get status, progress and spend
`GET`	`/people/search/{search_id}/results`	List the people found
`POST`	`/people/search/{search_id}/cancel`	Stop a search

Parse

Method	Path
`POST`	`/companies/search/parse`	Turn text into a company search request
`POST`	`/people/search/parse`	Turn text into a people search request

Personas

Method	Path
`GET`	`/personas`	List personas
`POST`	`/personas`	Create a persona
`GET`	`/personas/{persona_id}`	Get a persona
`PATCH`	`/personas/{persona_id}`	Update a persona
`DELETE`	`/personas/{persona_id}`	Delete a persona

Account

Method	Path
`GET`	`/me`	Check a key and get its workspace
`GET`	`/usage`	Get the credit balance and usage

Coming Soon

Monitor, Enrich and Ask 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.

Start

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

Poll

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

Read

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

See Search lifecycle and Poll and paginate.

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.

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:

{
  "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 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.

OpenAPI

The full contract is available as an OpenAPI 3.1 specification.

Base URL

Authentication

​Make your first request

​Authentication

​Endpoints

​Conventions

​Asynchronous searches

​Pagination

​Idempotency

​Rate limits

​Request IDs

​Errors

​Credits

​OpenAPI

Make your first request

Authentication

Endpoints

Conventions

Asynchronous searches

Pagination

Idempotency

Rate limits

Request IDs

Errors

Credits

OpenAPI