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:
- 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
- Access aggregated consumer intelligence datasets
- Pull AI intent signals & behavioral data
- Integrate marketplace data into your stack
- SLA-backed API with dedicated support
https://rareagents.aiAuthentication
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.
# Pass your key as a Bearer token in every request Authorization: Bearer ra_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Where to get your key
- Sign in at rareagents.ai/dashboard
- Go to Dashboard → API Keys (in the sidebar under "More")
- Click New Key, select an agent, name it, and generate
- Copy the
ra_...key — it's shown once only
Quick Start
Send your first message to an agent in under 2 minutes. You need: a free account, an agent, and an API key.
Go to rareagents.ai/dashboard, register, and create your first agent in "My Agents".
Open your agent → API tab → Generate Key. Copy the key (ra_...) — it won't be shown again.
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
{
"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
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
| Plan | Invocations / min | Tokens / month | API Keys / agent |
|---|---|---|---|
| Free | 5 | 50,000 | 2 |
| Pro | 60 | 10,000,000 | 10 |
| Elite | 300 | 100,000,000 | Unlimited |
| Corporate | Custom | Custom | Custom |
When rate limited, the API returns HTTP 429 Too Many Requests with a Retry-After header.
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)
// 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)
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)
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.