API Reference v1.0

Rare Agents Data API

Programmatic access to AI intent signals, consumer behavior feeds, and digital lifestyle intelligence. All data is opt-in, GDPR/CCPA compliant, and blockchain-anchored.

Overview

The Rare Agents Data API provides corporate buyers with programmatic access to the Data Exchange. All endpoints use HTTPS and return JSON by default. CSV output is available on download endpoints via the ?format=csv query parameter.

Base URL

https://rareagents.ai

Response Format

JSON (CSV optional)

Latency (p99)

< 200ms

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is issued after purchasing a dataset subscription from the Corporate Plans page.

Keep your API key secret. Never expose it in client-side code. Rotate keys from your account dashboard.

bash
# All requests must include this header
Authorization: Bearer ra_live_sk_your_key_here

Endpoints

GET/api/corporate/datasets Auth required

List all available dataset products with pricing and metadata.

Parameters

categorystring?Filter by category (ai_intent | consumer_behavior | digital_lifestyle)
deliverystring?Filter by delivery method (api | download | both)

Response

{
  "datasets": [
    {
      "id": "ai-intent-v1",
      "name": "AI Intent Dataset",
      "price_monthly": 2000,
      "update_frequency": "real_time",
      "delivery_methods": ["api", "csv"],
      "record_count_approx": 50000,
      "compliance": ["gdpr", "ccpa", "opt_in"]
    }
  ]
}
GET/api/corporate/datasets/:id/sample Auth required

Download a 100-record sample for a specific dataset.

Parameters

formatstring?Response format: json (default) | csv

Response

{
  "schema_version": "1.0",
  "dataset": "ai_intent_signals",
  "records": [
    {
      "record_id": "RAA00001",
      "category": "ai_tools",
      "ai_query": "best AI agent for email automation",
      "intent_score": 0.847,
      "topic_affinity": "high",
      "region": "US",
      "value_score": 76,
      "pii_removed": true,
      "consent_verified": true,
      "timestamp_utc": "2026-04-15"
    }
  ]
}
POST/api/corporate/datasets/:id/subscribe Auth required

Create a subscription to a dataset product. Returns a Stripe Checkout Session URL.

Parameters

billing_emailstringBilling contact email
delivery_methodstringapi | download | both

Response

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_...",
  "subscription_id": "sub_...",
  "access_key": "ra_live_sk_..."
}
GET/api/corporate/datasets/:id/stream Auth required

Stream real-time intent signals as NDJSON (AI Intent Dataset only). Requires active subscription.

Parameters

categoriesstring?Comma-separated category filter
min_intent_scorefloat?Minimum intent_score threshold (0.0–1.0)
regionstring?ISO country code filter

Response

{"record_id":"RAA10023","category":"ai_tools","intent_score":0.91,"region":"US","value_score":82,"timestamp_utc":"2026-06-16"}
{"record_id":"RAA10024","category":"automation","intent_score":0.74,"region":"GB","value_score":61,"timestamp_utc":"2026-06-16"}
GET/api/corporate/usage Auth required

Retrieve API usage for the current billing period.

Response

{
  "period_start": "2026-06-01",
  "period_end":   "2026-06-30",
  "requests_made": 1240,
  "records_delivered": 62000,
  "quota_requests": 50000,
  "quota_records": 2000000,
  "overage_usd": 0
}

Field Reference

All datasets share this base schema. Consumer Behavior and Digital Lifestyle feeds include additional category-specific fields documented in your subscription welcome email.

FieldTypeDescription
record_idstringUnique anonymised identifier (hex-encoded)
categoryenumai_tools | small_business | automation | productivity | developer_tools | marketing | finance | healthcare | ecommerce | education
ai_querystringAnonymised query or intent phrase
intent_scorefloatAI-calculated intent likelihood (0.0 – 1.0)
topic_affinityenumhigh | medium | low
regionstringISO 3166-1 alpha-2 country code
device_typeenumdesktop | mobile | tablet
session_depthintegerNumber of queries in the same intent session (1–10)
value_scoreintegerRAPIDS monetisation value score (0–100)
pii_removedbooleanPII scrubbing confirmed by RAPIDS pipeline
consent_verifiedbooleanExplicit user consent verified before inclusion
blockchain_anchoredbooleanProvenance anchored on Solana Memo Program
timestamp_utcdateCapture date (YYYY-MM-DD)

Code Examples

cURL

bash
curl -X GET "https://rareagents.ai/api/corporate/datasets" \
  -H "Authorization: Bearer ra_live_sk_your_key_here" \
  -H "Accept: application/json"

Python

python
import requests

BASE = "https://rareagents.ai/api/corporate"
HEADERS = {"Authorization": "Bearer ra_live_sk_your_key_here"}

# List datasets
r = requests.get(f"{BASE}/datasets", headers=HEADERS)
datasets = r.json()["datasets"]

# Stream AI intent signals
with requests.get(
    f"{BASE}/datasets/ai-intent-v1/stream",
    headers=HEADERS,
    params={"min_intent_score": "0.7", "region": "US"},
    stream=True
) as r:
    for line in r.iter_lines():
        if line:
            record = json.loads(line)
            print(record["intent_score"], record["ai_query"])

Node.js

javascript
import fetch from "node-fetch";

const BASE = "https://rareagents.ai/api/corporate";
const KEY  = "ra_live_sk_your_key_here";
const hdrs = { Authorization: `Bearer ${KEY}`, Accept: "application/json" };

// Fetch sample data
const res  = await fetch(`${BASE}/datasets/ai-intent-v1/sample?format=json`, { headers: hdrs });
const { records } = await res.json();

console.log(`Received ${records.length} sample records`);
records.filter(r => r.intent_score > 0.8).forEach(r =>
  console.log(r.record_id, r.ai_query, r.intent_score)
);

Rate Limits & SLA

PlanRequests / minRecords / monthUptime SLA
AI Intent ($2k/mo)602,000,00099.5%
Consumer Behavior ($3.5k/mo)1205,000,00099.5%
Digital Lifestyle ($5k/mo)30010,000,00099.9%
Enterprise (custom)CustomUnlimited99.99%

Need a custom integration?

Enterprise plans include dedicated onboarding, DPA signing, SFTP delivery, and custom schema mapping. Reach out to our data partnerships team.