RaportAgent REST API

Generate market-research reports programmatically. Create an API key in your account (Your account → API access), then call the API with Authorization: Bearer ra_live_…. An interactive schema is available at /docs (OpenAPI).

Authentication

Every /v1 request needs your key in the Authorization header:

Authorization: Bearer ra_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keep keys secret and server-side. Revoke a leaked key instantly from your account.

Endpoints

Create a report

curl -X POST https://raportagent.com/v1/reports \
  -H "Authorization: Bearer ra_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"EV charging infrastructure Europe 2026","options":{"depth":"deep"}}'

options.template (optional) shapes the report: compliance (legal/regulatory brief), pitch, saas, ecommerce, realestate, local. Unknown values fall back to the general report.

  -d '{"query":"crypto custody EU","options":{"depth":"deep","template":"compliance"}}'

Response (202 Accepted):

{
  "report_id": "rep_7f8a9b2c3d4e0011",
  "status": "queued",
  "estimated_duration_seconds": 900,
  "credits_charged": 1,
  "credits_remaining": 47
}

Idempotency: pass an Idempotency-Key header (any unique string per request) so a network retry never charges twice. A repeat with the same key returns the original report and 200 with "idempotent_replay": true and "credits_charged": 0.

Poll, then fetch (Python)

import time, requests
H = {"Authorization": "Bearer ra_live_xxx"}
BASE = "https://raportagent.com/v1"

rid = requests.post(f"{BASE}/reports", headers=H,
                    json={"query": "AI SaaS market Poland 2026"}).json()["report_id"]

while True:
    s = requests.get(f"{BASE}/reports/{rid}/status", headers=H).json()
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(30)

report = requests.get(f"{BASE}/reports/{rid}", headers=H).json()
print(report["content"]["markdown"])

Webhooks (optional)

Attach an HTTPS webhook to a key (in account settings) and we POST a signed report.completed / report.failed event when a run finishes. A signing secret is required when you set a webhook URL. Verify the X-RaportAgent-Signature: sha256=… HMAC using your webhook secret:

import hmac, hashlib
def verify(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Integrations

The same /v1 API powers two ready-made integrations, so you can generate sourced reports without writing any code:

MCP server — Claude Desktop, Claude Code, Cursor

The Model Context Protocol server puts RaportAgent inside any MCP client. Ask your assistant to research a market or map a regulatory landscape and it runs a full RaportAgent report, then pulls the finished markdown and its audit trail. Tools: generate_report (with template: compliance for a legal/regulatory brief), get_report_status, get_report, get_report_audit, list_reports, get_account. It is a thin wrapper over this API, so it inherits per-key rate limits, the credit model and the audit trail unchanged. Create an API key in your account, then point your MCP client at the @raportagent/mcp server with RAPORTAGENT_API_KEY.

Obsidian plugin

Generate sourced market-research reports straight from a note or a prompt, and pull finished reports (with YAML frontmatter — models, agents, sources) into your vault as clean Markdown. Configure it with your API key, base URL and target folder.

For access to either integration, or to self-host, get in touch.

Delivery & notifications — where finished reports land

Every account can push each finished report to the tools your team already uses — no code, no API key. Connect these under Your account → integrations:

• Slack — paste an Incoming Webhook URL; a "report ready" message is posted to the channel.
• Discord — paste a channel webhook URL; the report link is posted to the channel.
• Microsoft Teams — paste a channel webhook URL (classic connector or a Power Automate "Workflows" webhook); a card is posted to the channel.
• Notion — connect an internal integration + database; each report is written as a page.
• HubSpot — paste a private-app token (crm.objects.notes.write); each report is logged as a Note.
• Webhook — any https URL (Zapier, Make, n8n, or your own): a signed report.completed JSON event is POSTed with an X-RaportAgent-Signature header (sha256= HMAC of the body using your per-account secret). Outgoing URLs are SSRF-guarded (internal/metadata addresses are refused).

Errors & limits

Report creation is limited to 10/min per key; reads to 120–240/min. On a 429 the response carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window so clients can back off deterministically. A failed run refunds its credit automatically. All output is AI-generated — see AI transparency.