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:

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.

Quickstart with curl

  1. Get a key with the device flow, or create one in the dashboard.
  2. Start a team, wait for its plan, approve it, and collect leads:
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.

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: API keys, the device flow, and OAuth for MCP clients.
  • MCP: connecting each agent, and the tools.
  • API: endpoints, leads, formats, paging and long polls.
  • Errors: codes and what to do about them.
  • Credits: how spending works.
  • llms.txt and llms-full.txt: these docs for language models. Every page is also available as Markdown by adding .md to its URL.

This page as Markdown: /docs.md