Introduction

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:

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.

Keep API keys on your servers. Do not put them in browser or mobile code.

Credits

GET /usage 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:

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

Getting started

Account

Personas

Introduction

How it works

Account

Personas

Base URL

Authentication

Credits

Conventions

Rate limits

Errors

Next steps

Quickstart

Personas

​How it works

Account

Personas

​Base URL

​Authentication

​Credits

​Conventions

​Rate limits

​Errors

​Next steps

Quickstart

Personas

How it works

Base URL

Authentication

Credits

Conventions

Rate limits

Errors

Next steps