# Raven docs

Raven turns a brief ("independent wedding photographers in Oregon") into verified lead lists.
- **Planning:** a supervisor agent plans one **campaign** per audience segment, and each campaign is a lead list.
- **Research:** researcher agents find where those people are on the web, and a crawler collects the emails they publish.
- **Verification:** a verifier keeps a lead only if its email is on the source page and the person fits the brief.

Every lead comes with:
- the page its email was found on (`source_url`);
- the text around the email there (`evidence`);
- why the person fits (`fit_reason`);
- a one-sentence personal `line`.

Raven is built to be driven by coding agents: Claude Code, Codex, Gemini CLI, Cursor, or anything that speaks MCP or HTTP. New accounts get $5 of free credit, with no card needed.

## Quickstart for coding agents

Run this in a terminal, or ask your agent to:

```sh
npx -y @ravenoutreach/cli setup
```

1. It signs you up or in with one browser click.
2. It connects Raven to the coding agents installed on the machine. Each agent then signs in to Raven itself, with one click to approve.

Then ask your agent something like:

> Use Raven to find 50 independent bookstores in the Midwest that host author events. I sell an event-ticketing app for small venues.

To set up one agent at a time instead, see [MCP](/docs/mcp).

## Quickstart with curl

1. Get a key with the [device flow](/docs/authentication#device-flow), or create one in the dashboard.
2. Start a team, wait for its plan, approve it, and collect leads:

```sh
H="Authorization: Bearer $RAVEN_API_KEY"
API=https://api.ravenoutreach.com

curl -s $API/v1/teams -H "$H" -H 'Content-Type: application/json' \
  -d '{"brief":"Independent wedding photographers in Oregon with their own websites","product":"an online proofing gallery","daily_budget_usd":5}'

curl -s "$API/v1/teams/$TEAM?wait=45&wait_for=plan" -H "$H"        # repeat until status is awaiting_approval

curl -s -X POST $API/v1/teams/$TEAM/plan/approve -H "$H" \
  -H 'Content-Type: application/json' -d '{"version":1}'           # starts paid research

curl -s "$API/v1/leads?team_id=$TEAM&wait=55&format=markdown" -H "$H"
```

## How it works

| Concept | What it is |
|---|---|
| **Team** | A long-lived group of agents working on one brief, within a daily budget you set (default $5) and an optional lifetime spend limit. |
| **Plan** | What the supervisor proposes: campaigns, each with who qualifies, where to look, and a target number of verified leads. Nothing is researched until you approve a plan version. |
| **Campaign** | One audience segment and its lead list. When a campaign runs dry, the supervisor can add another, if `auto_add_campaigns` is on. |
| **Lead** | A person whose email is published on their own site and who fits the campaign. A lead is unique within your account: you never pay twice for the same person. |

### Team statuses

| Status | Meaning |
|---|---|
| `planning` | The supervisor is writing the plan. |
| `awaiting_approval` | A plan is ready for review. |
| `running` | Research is underway. |
| `paused` | You paused it, or it reached its spend limit (`status_reason` says which). Raising the limit resumes it. |
| `budget_paused` | Today's budget is spent. Research resumes at midnight in the account's time zone, or as soon as you raise the budget. |
| `out_of_credits` | The account has no credit. The team resumes once you top up. |
| `usage_limited` | The account hit its monthly usage limit. |
| `completed` | Every campaign reached its target. Raise a target to continue. |
| `archived` | The team is stopped for good. |

### Timing and cost

- **Planning** takes a minute or two.
- **First leads** usually arrive 15–30 minutes after approval, and lists keep growing for hours.
- **Cost** starts around $0.08 per verified lead, and rises when few of the people you want publish an email. See [credits](/docs/credits).

### Who Raven can find

Raven finds people who publish a contact email on their own website. It works best for small businesses, freelancers, creators and local services. Staff of large companies rarely qualify.

## More

- [Authentication](/docs/authentication): API keys, the device flow, and OAuth for MCP clients.
- [MCP](/docs/mcp): connecting each agent, and the tools.
- [API](/docs/api): endpoints, leads, formats, paging and long polls.
- [Errors](/docs/errors): codes and what to do about them.
- [Credits](/docs/credits): how spending works.
- [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt): these docs for language models. Every page is also available as Markdown by adding `.md` to its URL.