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

# Agents

> Hand a search to an AI agent: setup, the workflow that works, and a prompt to start from.

> Agents: the full documentation index is at [/llms.txt](https://docs.revcenter.ai/llms.txt).

Revcenter is built to be driven by an agent: every action is a deterministic call, results are structured
JSON, and nothing spends without the call that says so.

## Give your agent access

1. Create a key under **Settings → Usage → API** and set it as `REVCENTER_API_KEY` where the agent runs.
2. Let the agent call the API at `https://api.revcenter.ai/v1` with `Authorization: Bearer $REVCENTER_API_KEY`
   (any agent that can run `curl` or make HTTP requests can). The [MCP server](/tools/mcp) and the
   [CLI](/tools/cli) are coming soon.
3. Point the agent at the docs first: `https://docs.revcenter.ai/llms.txt` lists every page, and any page's
   address with `.md` added gives it as plain text. `https://docs.revcenter.ai/llms-full.txt` is all of it in one file.

## The workflow

Each step names the API call; the [MCP tools](/tools/mcp) and [CLI commands](/tools/cli), coming soon, do the same.

1. **Read the criteria reference** (`GET /v1/reference/criteria`) so the agent knows which fields filter
   LinkedIn before anything is bought and which only score.
2. **Write criteria from the role.** Put requirements in the fields that filter (titles, place, seniority,
   years, current industries, employers, schools). Put things that must be evidenced on a profile, such as
   certifications and licenses, in `must_have`, each one short (`"CPA"`, `"PE license"`).
3. **Make a project, launch one search** (`POST /v1/projects`, then `POST /v1/projects/{id}/searches` with an
   `Idempotency-Key`), and poll `GET /v1/searches/{id}` until it finishes. A retry with the same key and request
   never starts a second search.
4. **Read the people** (`GET /v1/searches/{id}/people?min_score=80`). Check the outcome: *Shortlist ready*
   (6 or more), *Poor yield* (1 to 5) or *No results*.
5. **Refine without spending:** preview a cut-off or weight change (`POST /v1/searches/{id}/scoring/preview`),
   apply it if it helps (`…/scoring/apply`), or search the workspace's own candidates again
   (`POST /v1/searches/{id}/database-pass`).
6. **Only then expand** (`POST /v1/projects/{id}/expand`), which uses 1 more shortlist credit.
7. **Export** the shortlist (`GET /v1/projects/{id}/shortlist` or `…/shortlist.csv`).

## A prompt to start from

```text theme={null}
Use the Revcenter API for this role. First read https://docs.revcenter.ai/llms.txt.
Call https://api.revcenter.ai/v1 with the header "Authorization: Bearer $REVCENTER_API_KEY"; the key is in
my environment, so never print it. Before launching a search or expanding one (each uses 1 shortlist
credit), tell me and wait for my OK. Role: <paste the job description or the brief>.
1. Read GET /v1/reference/criteria and draft criteria; show them to me. 2. After I approve, create a
project and launch one search with an Idempotency-Key, then poll it until it finishes. 3. Show the people
scoring 80 or more, with why each fits. 4. Suggest scoring changes, preview them, and apply only what I
approve. 5. Save the shortlist CSV.
```

## Good practice

* Ask before spending: only launching a search (unless `database_only`) and expanding use shortlist credits,
  1 each.
* Retry with the same idempotency key, and respect `429` responses and their `Retry-After` header. See
  [rate limits](/guides/rate-limits) and [errors](/guides/errors).
* Keep the key in the environment, never in the prompt or a file the agent writes.

## Recipes

* [Run a search from a coding agent](/recipes/coding-agent)
* [Run a search from a backend job](/recipes/backend-job)


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