API Reference — v1

Rare Agents API Docs

Everything you need to invoke agents, manage approvals, access intelligence data, and integrate AI into your product — for individual users and enterprise teams alike.

Overview

The Rare Agents API lets you interact with AI agents programmatically — trigger conversations, approve or reject agent tool calls, and pull intelligence data from the platform. There are two primary audiences:

Individual Users
  • Invoke your agents via REST from any app
  • Manage human approval gates
  • Export training data you've contributed
  • Automate agent tasks via cron or webhook
Companies & Enterprise
  • Access aggregated consumer intelligence datasets
  • Pull AI intent signals & behavioral data
  • Integrate marketplace data into your stack
  • SLA-backed API with dedicated support
Base URL for all API calls: https://rareagents.ai

Authentication

All API requests (except the public agent invocation endpoint) require a Bearer token in the Authorization header. Tokens are generated per-agent inside your dashboard.

API Key Format

All API keys are prefixed with ra_ followed by a 32-character hex string. Keys are shown only once at creation — store them securely.

bash
# Pass your key as a Bearer token in every request
Authorization: Bearer ra_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Where to get your key

  1. Sign in at rareagents.ai/dashboard
  2. Go to Dashboard → API Keys (in the sidebar under "More")
  3. Click New Key, select an agent, name it, and generate
  4. Copy the ra_... key — it's shown once only
API keys grant full access to that agent on your behalf. Never commit them to source control or expose them client-side.

Quick Start

Send your first message to an agent in under 2 minutes. You need: a free account, an agent, and an API key.

1Create a free account and an agent

Go to rareagents.ai/dashboard, register, and create your first agent in "My Agents".

2Generate an API key

Open your agent → API tab → Generate Key. Copy the key (ra_...) — it won't be shown again.

3Invoke your agent
curl -X POST https://rareagents.ai/api/invoke/YOUR_AGENT_ID \
  -H "Authorization: Bearer ra_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the latest AI trends for me",
    "stream": false
  }'

Sample Response

json
{
  "reply": "Here are the key AI trends for June 2026:\n\n1. **Multimodal models** ...",
  "agentId": 42,
  "conversationId": 1891,
  "tokensUsed": 812,
  "model": "rare-agents/intelligence-v1"
}

Agent Invocation API

The invocation endpoint lets any external application send messages to your agent and receive AI responses. This is the core building block for integrating Rare Agents into your product.

Approval Gates API

When an agent tries to run a sensitive tool (web search, file write, external API call) and you have approval gates enabled, the action is paused until you approve or reject it. Use these endpoints to build your own approval UI or automate the decision.

API Key Management

Each agent can have multiple named API keys. Use these endpoints to programmatically rotate, create, or revoke keys — useful for CI/CD pipelines or multi-environment setups.

Model Intelligence API

Access your RA Intelligence model training contributions, quality statistics, and configure a custom fine-tuned endpoint if you're on an Elite plan.

Corporate Data API

Corporate API access requires a purchased dataset or data bundle. View corporate plans →

Companies can access aggregated, anonymized consumer intent signals, behavioral data, and AI interaction datasets collected from consenting Rare Agents users. All data is GDPR-compliant and PII-free.

Rate Limits

PlanInvocations / minTokens / monthAPI Keys / agent
Free550,0002
Pro6010,000,00010
Elite300100,000,000Unlimited
CorporateCustomCustomCustom

When rate limited, the API returns HTTP 429 Too Many Requests with a Retry-After header.

json
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "Rate limit exceeded. Retry after 12 seconds." }

SDKs & Examples

Official SDKs are coming soon. In the meantime, the REST API works with any HTTP client. Here are some complete integration examples.

Webhook / Cron Automation (Node.js)

javascript
// Run your agent on a schedule (e.g. with node-cron)
import cron from 'node-cron';

const AGENT_ID = 42;
const API_KEY  = process.env.RA_API_KEY; // ra_...

cron.schedule('0 9 * * 1-5', async () => {
  // Every weekday at 9am — ask the agent for a market brief
  const res = await fetch(`https://rareagents.ai/api/invoke/${AGENT_ID}`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Give me this morning\'s market brief' }),
  });
  const data = await res.json();
  console.log('[Daily Brief]', data.reply);
});

Auto-Approve Low-Risk Tools (Python)

python
import requests, time

BASE = 'https://rareagents.ai'
KEY  = 'ra_YOUR_KEY'
HEADERS = {'Authorization': f'Bearer {KEY}'}
LOW_RISK = {'web_search', 'get_weather', 'read_file'}

def poll_and_auto_approve():
    while True:
        r = requests.get(f'{BASE}/api/approvals', headers=HEADERS)
        for approval in r.json().get('approvals', []):
            tool = approval['toolName']
            action = 'approve' if tool in LOW_RISK else None
            if action:
                requests.post(
                    f'{BASE}/api/approvals/{approval["id"]}/{action}',
                    headers=HEADERS
                )
                print(f'Auto-approved: {tool}')
        time.sleep(5)

poll_and_auto_approve()

Corporate Data Sync (Python)

python
import requests, json

CORP_KEY = 'corp_YOUR_KEY'
HEADERS  = {'Authorization': f'Bearer {CORP_KEY}'}

# Fetch latest AI intent signals
r = requests.get(
    'https://rareagents.ai/api/corporate/signals',
    headers=HEADERS,
    params={
        'category': 'purchase_intent',
        'since':    '2026-06-01',
        'limit':    500,
    }
)

signals = r.json()['signals']

# Save to your data warehouse
with open('intent_signals.jsonl', 'w') as f:
    for signal in signals:
        f.write(json.dumps(signal) + '\n')

print(f'Synced {len(signals)} signals')

Ready to build?

Create your free account, spin up an agent, and generate an API key in under 2 minutes. No credit card required.