Data APIFor AI agents
Give your agent a research tool it can cite.
Wrap search in a function and let an agent call it with whatever the user asks for. The agent gets structured records and the sources behind each one, not a page of search results to guess from.
From a function to a tool.
One function for the agent to call, docs a coding agent can read, and a cap on spend.
Wrap search in a function
The function starts a search, waits for it and returns the results. The full version is in the docs' Build with AI page.
def find_companies(query: str, limit: int = 10) -> list[dict]: """Find companies matching a description. Each result includes evidence with sources.""" ...Let a coding agent build it
The docs are written for agents as well as people: every page as Markdown, an llms.txt index, an OpenAPI spec and an integration brief to paste into Claude Code, Cursor or Codex. This is part of the brief.
API FACTS - Base URL: https://api.avina.io/v1 - Auth: "Authorization: Bearer <key>" - Start: POST /companies/search - Status: GET /companies/search/{id}/status - Results: GET /companies/search/{id}/results - Cancel: POST /companies/search/{id}/cancelCap what an agent can spend
Set max_credits on every search an agent starts. While you build, keep the limit small too.
POST /v1/companies/search { "query": "Privately held dental practices in Texas hiring SDRs", "limit": 5, "max_credits": 5 }
Why give agents the Data API.
- Records, not web pages
- Results come back in one schema whichever provider found them: a name, a domain, the fields you filtered on. The agent does not have to parse a page to answer.
- Sources on every claim
- Each requirement on a result has a verdict, a summary of the evidence and its sources. When the evidence is missing, the answer is unknown, not a guess.
- Bounded and safe to retry
- max_credits caps a search. An Idempotency-Key on the request means a retry does not start, or charge for, a second search.
How a request is answered.
Every search goes through the same four stages. You do not choose providers, and you can see what each stage did.
Interpret
The request is turned into exact requirements: filters on known fields, and free-text criteria for anything no field covers. Nothing you asked for is dropped.
Route
Avina picks the sources from what the request contains: data providers for structured conditions, AI search of the public web for requirements that need research.
Verify
Each candidate is checked against every requirement. It passes only when every requirement is matched with evidence.
Return
Passing records are merged into one per company or person and added to the results, which you can read while the search is still running.
The APIs behind it.
One key covers all of them. Each links to its page in the docs. See all seven.
- CompaniesAvailableFind companies by anything you can describe: filters, requirements no database covers, and events like a new hire or a funding round.
POST /v1/companies/search - PeopleAvailableFind people by job title, seniority and employer, with verified work emails on request.
POST /v1/people/search - ParseAvailableTurn plain language into structured filters you can show, edit and reuse. Free.
POST /v1/companies/search/parse - AskComing soonAsk a question about a company or market and get an answer with citations.
More ways to use the Data API.
Common questions
How does an agent call the Data API?
Through a function you define. It starts a search, polls its status and returns the results. The docs' Build with AI page has the full function and a brief a coding agent can follow to write the integration.
Can an agent run up a bill?
Not past the cap you set. max_credits limits what one search can spend, and an Idempotency-Key stops a retried request from starting a second search. Reading status and results is free.
What does the agent get back?
Structured records for companies or people, each with the requirements it was checked against, a verdict for each one, and the evidence with its sources.
How do I get access?
The Data API is in beta. Request access with the form in the docs. Once you are in, a workspace admin creates an API key in the Avina dashboard and adds credits, and the quickstart takes you to your first results.
One tool for “find companies like this”.
Request beta access and give your agent its first search.
The Data API is in beta. Access is by request.