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.