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

# Introduction

> Call Avina from your own servers with the Avina API.

The Avina API lets your servers work with your Avina workspace over REST. It currently covers your account (which workspace a key belongs to and its credit usage) and personas, the contact-targeting settings Avina uses to find contacts at the companies your signals surface.

## How it works

> **Account**
>
> Check which workspace an API key belongs to, and how many signal credits the workspace has used this billing period.

> **Personas**
>
> A persona is a set of job titles to look for at each company, with how many contacts to find and whether to enrich emails and phones. Personas are shared with the Avina dashboard.

## Base URL

```
https://api.avina.io/v1
```

## Authentication

Every request needs a workspace API key in the `Authorization` header:

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

Workspace admins create and revoke keys in the dashboard under **Settings → API Keys**. A key is shown once, when you create it. A key acts for its whole workspace: it can read and change that workspace's personas.

> [!WARNING]
>
> Keep API keys on your servers. Do not put them in browser or mobile code.

## Credits

[`GET /usage`](/api-reference/account/get-signal-credit-usage-for-the-current-billing-period) reports your workspace's signal credits for the current billing period, the same credits and period the dashboard shows. Creating or changing a persona does not use credits.

## Conventions

* **JSON** request and response bodies with `snake_case` fields. Every object has an `object` field (`api_key`, `usage`, `persona`, `list`).
* **Timestamps** are UTC ISO 8601, for example `2026-10-05T17:02:11Z`.
* **Idempotency:** `POST` requests accept an `Idempotency-Key` header (any unique string, kept for 24 hours). Retrying with the same key returns the first response instead of repeating the action. Reusing a key with a different body returns `409 idempotency_key_reused`.
* **Request ids:** every response has an `X-Request-Id` header. Include it when you contact support.
* **Bodies:** request bodies must be JSON (`Content-Type: application/json`) and are limited to 100 KB.

## Rate limits

Each API key can make 120 requests per minute. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers; over the limit, requests get `429 rate_limited`. Wait `RateLimit-Reset` seconds before retrying.

## Errors

Errors use one shape:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "foo is not a recognized field",
    "request_id": "req_8f2a",
    "details": [{ "field": "foo", "message": "is not a recognized field" }]
  }
}
```

| HTTP | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | The request is invalid; `details` names the fields |
| 401 | `invalid_api_key` | The key is missing, invalid or revoked |
| 404 | `not_found` | No such object in this workspace |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used with a different request |
| 413 | `invalid_request` | The request body is larger than 100 KB |
| 415 | `invalid_request` | The request body is not JSON; send it as `application/json` |
| 429 | `rate_limited` | Too many requests |
| 500 / 503 | `internal_error` | Something went wrong on our side; retry the request |
| 504 | `timeout` | The request took too long; retry it |

## Next steps

> **[Quickstart](/api-reference/quickstart.md)**
>
> Check your key, read your credit usage, and create a persona.

> **[Personas](/api-reference/personas/list-personas.md)**
>
> The persona endpoints.


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