Skip to documentation
reach agentsDocumentation
OpenAPI spec
Documentation Agent Kit

ReachAgents Agent Kit

Give your agent the tools to find leads, prepare campaigns and report on results. Works with Codex, Claude Code, Hermes and OpenClaw.

Kit 2026.10.27.2 · API 1.1.0 · 62 operations

Download

Install the kit

Requires Python 3.9+ and a signed-in local agent runtime. Choose your runtime, then run these commands in your terminal. Each installed skill includes its own CLI and API schemas.

Bash
curl -L https://reachagents.ai/downloads/reachagents-agent-kit.zip -o reachagents-agent-kit.zip
unzip -o reachagents-agent-kit.zip -d reachagents-agent-kit
cd reachagents-agent-kit
./install.sh --runtime codex --env production

Installs personal Codex skills. Add --project-dir PATH for a project installation.

The default production install points agents at https://api.reachagents.ai and https://app.reachagents.ai.

For non-production testing, open Settings → API Keys on the non-production app and copy the generated install command from there.

First use

Configure your connection

From the extracted reachagents-agent-kit directory, run the CLI below and enter your scoped API key at its hidden prompt. The shared credential file stays on your computer with private permissions; it is not copied into chat.

Bash
reachagents_cli="./bin/reachagents-api"
python3 "$reachagents_cli" configure
python3 "$reachagents_cli" doctor
python3 "$reachagents_cli" GET /v1/whoami

For an installed CLI, Codex users can use ~/.agents/skills/reachagents-operator-account-setup/scripts/reachagents-api; Claude Code users can use ~/.claude/skills/reachagents-operator-account-setup/scripts/reachagents-api. Both runtimes read ~/.config/reachagents/env; environment overrides take precedence. A desktop session can use this file without depending on exports from another terminal.

Start a new session in your agent runtime and ask: “Use the ReachAgents operator skills. Check my connection, list accessible workspaces, and explain what blocks outreach. Do not create, run or send anything.”

For project-local skills, add --project-dir /absolute/path/to/project to the install command. Choose one runtime with --runtime codex or --runtime claude. Hermes uses --runtime hermes; OpenClaw uses --runtime openclaw --openclaw-dir PATH. Claude support here means Claude Code with local shell access.

The agent should discover its installed skill, use the CLI beside it, select the requested workspace and return a report with app links. Before a write, approve the exact action. The CLI blocks unconfirmed writes before making an API request.

What can I ask?

Put your agent to work

Find leads, prepare campaigns, review your Inbox and understand your results. Pick a task below for a ready-to-use instruction.

25 prompts · 6 categories · All four runtimes

Copy a prompt, replace the details in [brackets] and paste it into your agent. Start with an installed kit and a configured API key. Drafts keep discovery or sending off. Review prompts ask for your approval.

Lead Agents

Find people showing relevant interests, needs and buying signals on X, YouTube, TikTok or LinkedIn, where available.

A saved agent you can review before discovery starts.

Use the installed ReachAgents operator skills in workspace "[workspace name]". If the workspace is ambiguous, ask me to choose. Create a Lead Agent called [agent name] to find [ideal customer, e.g. founders of small SaaS companies] who show [signal, e.g. asking for an AI customer-support tool] on [X, YouTube, TikTok or LinkedIn]. Request 25 leads per run. Keep automatic discovery and scheduling off; do not start a run. Show me its criteria and the link to review it. Flag any source unavailable in my workspace.

Availability depends on your key permissions, connected accounts and enabled channels. See API coverage for exact fields and permissions. A queued run is not a delivery receipt.

Public API

Current API coverage

Use the same scoped API key for setup, discovery, campaigns and Inbox. The kit includes the full request and response schemas and an operation list beside every installed skill.

Download the OpenAPI contract
Campaign draft helpers
ChannelEndpointSender field
X DMPOST /v1/campaigns/x-dmx_account_id
EmailPOST /v1/campaigns/emailemail_account_ids
LinkedInPOST /v1/campaigns/linkedinlinkedin_account_id
TelegramPOST /v1/campaigns/telegramtelegram_account_id
WhatsAppPOST /v1/campaigns/whatsappwhatsapp_account_id
InstagramPOST /v1/campaigns/instagraminstagram_account_id
  • Setup: company/workspace profiles, communication style, onboarding readiness and website analysis.
  • Discovery and contacts: X, YouTube, TikTok and LinkedIn agents, lead limits, contact groups, profile links and source evidence. People Search availability is controlled by the server.
  • Campaign operations: sender accounts, audience previews, target states, email events, health summaries and safe deletion of inactive drafts.
  • Inbox: six-channel conversation reads, sender and response filters, approved text replies, automation policies and candidate review.
  • Run tracking: run status, logs, cancellation and batch requests. A queued run does not prove delivery.
  • YouTube data: single or batch video lookups with the optional data:read scope. Fresh crawls can use your balance and the daily crawl quota.

WhatsApp and Instagram sending, campaigns and automation depend on separate server rollout gates, account state and limits. Text replies support email, LinkedIn, Telegram, WhatsApp and Instagram; X conversation sends currently return unsupported_platform. Instagram text is limited to 1,000 characters; other accepted text to 8,000. API replies cannot send attachments or post into Telegram, WhatsApp or Instagram groups.

Campaign summary usage counters cover X, LinkedIn and email. Use target and message evidence for newer channels; zero summary counts do not prove that nothing was sent. If a send result is unconfirmed, inspect the conversation before retrying.

All 62 API operations and scopes
Method / pathOperationRequired scopes
GET /v1/youtube-videos/{video}Get YouTube video metricsdata:read
GET /v1/youtube-videosBatch YouTube video metricsdata:read
GET /v1/whoamiInspect the authenticated API keyValid API key
GET /v1/companyGet company detailsworkspaces:read
PATCH /v1/companyUpdate company profile detailsworkspaces:write
GET /v1/workspacesList accessible workspacesworkspaces:read
GET /v1/workspaces/{workspace_id}Get one workspaceworkspaces:read
PATCH /v1/workspaces/{workspace_id}Update workspace detailsworkspaces:write
GET /v1/agentsList agentsagents:read
POST /v1/agentsCreate a lead agent and start discovery by defaultagents:write, agents:run
GET /v1/agents/{agent_id}Get one agentagents:read
PATCH /v1/agents/{agent_id}Update a lead agentagents:write
DELETE /v1/agents/{agent_id}Delete a non-running lead agentagents:write
POST /v1/agents/{agent_id}/runQueue an agent discovery runagents:run
GET /v1/contactsList contactscontacts:read
POST /v1/contactsCreate or upsert a contactcontacts:write
PATCH /v1/contactsPatch a contact by ID in the request bodycontacts:write
PATCH /v1/contacts/{contact_id}Patch a contactcontacts:write
POST /v1/contacts/bulkBulk import contactscontacts:write
GET /v1/contact-groupsList contact groupscontact_groups:read
POST /v1/contact-groupsCreate a contact groupcontact_groups:write
POST /v1/contact-groups/{group_id}/contactsAdd contacts to a groupcontact_groups:write
DELETE /v1/contact-groups/{group_id}/contacts/{contact_id}Remove one contact from a groupcontact_groups:write
GET /v1/campaignsList campaignscampaigns:read
POST /v1/campaignsCreate a campaign draftcampaigns:write
PATCH /v1/campaignsPatch a campaign by ID in the request bodycampaigns:write
POST /v1/campaigns/linkedinCreate a LinkedIn campaign draftcampaigns:write
GET /v1/campaigns/{campaign_id}Get one campaigncampaigns:read
PATCH /v1/campaigns/{campaign_id}Patch a campaign draft/configurationcampaigns:write
DELETE /v1/campaigns/{campaign_id}Delete an inactive campaign draftcampaigns:write
POST /v1/campaigns/{campaign_id}/previewPreview a campaign audience/messages without sendingcampaigns:read
POST /v1/campaigns/{campaign_id}/runQueue a campaign runcampaigns:run
POST /v1/runs/batchQueue multiple agent/campaign runsagents:run, campaigns:run
GET /v1/runs/{run_id}Get run statusruns:read
GET /v1/runs/{run_id}/logsGet run logsruns:read
POST /v1/runs/{run_id}/cancelCancel a queued or running runruns:cancel
GET /v1/conversationsList inbox conversationscontacts:read
GET /v1/conversations/{conversation_id}/messagesList conversation messagescontacts:read
POST /v1/conversations/{conversation_id}/messagesSend or draft a conversation messagecontacts:write
GET /agentsLegacy alias for GET /v1/agentsValid API key
POST /leadsLegacy alias for POST /v1/contactsValid API key
POST /leads/bulkLegacy alias for POST /v1/contacts/bulkValid API key
GET /v1/inbox-automation/policiesList inbox automation policiesinbox_automation:read
POST /v1/inbox-automation/policiesCreate or update an inbox automation policyinbox_automation:write
PUT /v1/inbox-automation/policiesCreate or update an inbox automation policyinbox_automation:write
GET /v1/inbox-automation/candidatesList inbox automation candidatesinbox_automation:read
PATCH /v1/inbox-automation/candidates/{candidate_id}Patch an inbox automation candidateinbox_automation:write
POST /v1/inbox-automation/candidates/{candidate_id}/sendSend an inbox automation candidate replyinbox_automation:run
POST /v1/inbox-automation/runRun inbox automation manuallyinbox_automation:run
GET /v1/onboarding/readinessDiagnose onboarding readiness for a workspaceworkspaces:read
POST /v1/onboarding/analyze-websiteAnalyze a website into a ReachAgents business profileworkspaces:read
POST /v1/onboarding/setupApply onboarding business profile to company and workspaceworkspaces:write
POST /v1/campaigns/whatsappCreate a WhatsApp campaign draftcampaigns:write
POST /v1/campaigns/instagramCreate a Instagram campaign draftcampaigns:write
POST /v1/campaigns/telegramCreate a Telegram campaign draftcampaigns:write
GET /v1/sender-accountsList sender accountscampaigns:read
POST /v1/campaigns/x-dmCreate an X DM campaign draftcampaigns:write
POST /v1/campaigns/emailCreate an email campaign draftcampaigns:write
GET /v1/campaigns/{campaign_id}/targetsList campaign targetscampaigns:read
GET /v1/campaigns/{campaign_id}/eventsList campaign email eventscampaigns:read
GET /v1/campaigns/{campaign_id}/summaryGet campaign health and delivery summarycampaigns:read
PATCH /v1/campaigns/{campaign_id}/targets/{target_id}Update a campaign targetcampaigns:write

Creating an agent starts discovery by default and needs agents:run as well as agents:write. Use auto_run: false for a manual draft. Batch scope requirements depend on the submitted items; the OpenAPI contract describes each operation.

Kit 2026.10.27.2

Update an existing installation

Download the latest kit and rerun the installer. It updates the bundled ReachAgents operator skills, references, bridge and CLI. Existing environment values and other skills are preserved. Choose Codex and Claude Code with --runtime codex,claude; add --project-dir PATH for project-local skills. Hermes and OpenClaw remain supported with their runtime flags.

Existing keys keep their current permissions. Add data:read only if you need YouTube data. Start with read scopes for reporting and add write/run scopes for the actions you approve.

Bash
reachagents_cli="$HOME/.agents/skills/reachagents-operator-account-setup/scripts/reachagents-api"
python3 "$reachagents_cli" GET /v1/whoami
python3 "$reachagents_cli" GET /v1/workspaces
python3 "$reachagents_cli" GET /v1/sender-accounts --query workspace_id=YOUR_WORKSPACE_ID
python3 "$reachagents_cli" GET /v1/campaigns/CAMPAIGN_ID/summary --query workspace_id=YOUR_WORKSPACE_ID

Read-only sender and run requests work without mutation confirmation. Use confirmed=true in the bridge or --confirm in the CLI after approving a mutation. Reuse the same idempotency key when retrying the same approved action.

Credentials

Create a ReachAgents API key

Where to create it

Open ReachAgents Settings → API Keys, create a key, copy it once, and save it locally with the CLI configure command. The key is used as REACHAGENTS_API_KEY.

Open API keys

Full operator scopes

workspaces:readworkspaces:writeagents:readagents:writeagents:runcontacts:readcontacts:writecontact_groups:readcontact_groups:writecampaigns:readcampaigns:writecampaigns:runinbox_automation:readinbox_automation:writeinbox_automation:runruns:readruns:canceldata:read

Approval model

Safe operations for customer agents

What agents can do

  • Read-only reporting can run after you provide a scoped API key.
  • Creating, updating, deleting, running, sending, canceling, or bulk importing always requires explicit approval.
  • API keys stay in your local agent runtime. Do not paste them into chat, logs, reports, or task descriptions.
  • Customer-facing reports should include the exact ReachAgents page link to open next.

Public API coverage

The bundled CLI covers every operation in the Public API contract. Hermes can also use reachagents_api_request. Mutating and live operations require confirmed=true after the user approves the exact action.

Download the latest kit

Connect your agent to Reach Agents.

Create a workspace, get an API key and run your first request.

Start free

7-day free trial. No card needed.

Get an API key