REST API reference

Authentication

Create an API key in the portal (app.signalraven.ai → Settings → API keys), then use the OAuth client_credentialsgrant to get a bearer token (≈30 min lifetime), and call the API with it.

# 1. Get a token
curl -s -X POST https://auth.signalraven.ai/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d 'scope=read:signals read:sources read:icp'

# 2. Call the API
curl -s https://api.signalraven.ai/api/v1/signals?limit=5 \
  -H "Authorization: Bearer eyJ…"

Scopes

A token only works on endpoints matching its scopes; anything else returns 403 insufficient_scope. Every response carries a _meta.mode of "live" or "sample" (see approved vs. sample data).

GET /signals

List signals, newest first.

{
  "data": [
    {
      "id": "8af4c6c7-…",
      "type": "KEYWORD_SEARCH_REACTION",
      "strength": 9,
      "person": { "company": "Globex", "linkedinUrl": "https://…", "location": "New York, US" },
      "whyItMatters": "Publicly weighing a multi-CDN migration …",
      "suggestedOpener": "Saw your note on tail-latency …",
      "talkingPoints": ["Multi-CDN failover", "Live-event QoE"],
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "total": 866,
  "limit": 25,
  "offset": 0,
  "_meta": { "mode": "live" }
}

GET /signals/{id}

Fetch one signal by id. Returns { data, _meta }, or 404 if not found.

GET /sources

List monitored sources with activity metrics. Query period = 7, 30 (default), or all (days). Each source includes type, linkedinUrl, displayName, isActive, strengthScore, signalCount, totalPosts, qualifiedPosts.

GET /watchlist

List watchlist posts (limit 1–100, offset). Each post: sourceId, url, author, preview, relevanceScore, lifecycleStatus, createdAt.

GET /icp

The workspace’s default ICP profile: minEmployees, maxEmployees, targetIndustries, targetTitles, targetPersonas, targetSeniority, additionalContext. 404 if none configured.

Errors