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.

  1. 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."""
        ...
    
  2. 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}/cancel
    
  3. Cap 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.

  1. 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.

  2. 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.

  3. Verify

    Each candidate is checked against every requirement. It passes only when every requirement is matched with evidence.

  4. 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.

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.