Language
API Reference

REST API · v0

40 read-only endpoints over the corpus. All requests require a Bearer token. Base URL: https://app.aidran.ai

GETread-only
POSTsearch / write
501not implemented

Records

Discourse records ingested from public source kinds.
5 endpoints
GET/v1/records

Cursor-paginated list, filterable by source, sentiment, and time window.

AuthorizationBearer tokenrequired
Query parameters
sourcestringoptionalPlatform. One of: reddit · bluesky · arxiv · hackernews · youtube · google_news · exa · webset · huggingface · twitter
sentimentstringoptionalSentiment label. One of: positive · neutral · negative
fromISO 8601optionalTime window start (inclusive)
toISO 8601optionalTime window end (inclusive)
limitintegeroptionalItems per page. Default 20 · max 100
cursorstringoptionalOpaque pagination cursor from previous nextCursor
curl
$ curl https://app.aidran.ai/v1/records \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "id": "r_2611_0c41",
      "source": "reddit",
      "title": "On post-deployment monitoring of LLMs",
      "url": "https://reddit.com/r/MachineLearning/...",
      "publishedAt": "2026-05-09T06:11:00Z",
      "sentimentScore": -0.34,
      "sentimentLabel": "negative"
    }
  ],
  "nextCursor": "eyJ0czoxNzM...",
  "total": 486142
}
Status codes
200OK — items array with nextCursor
400Invalid filter parameters
401Unauthorized
GET/v1/records/{id}

Single record with full content and source metadata.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredRecord ID
curl
$ curl https://app.aidran.ai/v1/records/{id} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "r_2611_0c41",
  "source": "reddit",
  "title": "On post-deployment monitoring of LLMs",
  "content": "Full text content of the record...",
  "url": "https://reddit.com/r/MachineLearning/...",
  "publishedAt": "2026-05-09T06:11:00Z",
  "sentimentScore": -0.34,
  "sentimentLabel": "negative",
  "metadata": { "subreddit": "MachineLearning", "score": 847 }
}
Status codes
200OK
401Unauthorized
404Record not found
GET/v1/records/{id}/embedding

512-dim voyage-4-lite embedding vector.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredRecord ID
curl
$ curl https://app.aidran.ai/v1/records/{id}/embedding \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "recordId": "r_2611_0c41",
  "model": "voyage-4-lite",
  "dimensions": 512,
  "embedding": [0.021, -0.143, 0.087, "... 512 floats total ..."]
}
Status codes
200OK
401Unauthorized
404Record not found
GET/v1/records/{id}/entities

Entity mentions attached to the record.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredRecord ID
Query parameters
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/records/{id}/entities \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "entityId": "entity_openai_42",
      "name": "OpenAI",
      "type": "org",
      "mentionCount": 3,
      "positions": [42, 187, 901]
    }
  ],
  "nextCursor": null,
  "total": 4
}
Status codes
200OK
401Unauthorized
404Record not found
GET/v1/records/{id}/topics

Topic assignments for the record.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredRecord ID
curl
$ curl https://app.aidran.ai/v1/records/{id}/topics \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "topicId": "topic_governance_4a1b",
      "label": "Governance",
      "slug": "governance",
      "confidence": 0.87
    }
  ]
}
Status codes
200OK
401Unauthorized
404Record not found

Stories

AI-generated editorial stories with citations and provenance.
9 endpoints
GET/v1/stories/lead

Current lead story.

AuthorizationBearer tokenrequired
curl
$ curl https://app.aidran.ai/v1/stories/lead \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "s_lead_4f2a",
  "slug": "sentiment-diverges-reddit-bluesky",
  "headline": "Sentiment on AI regulation diverges sharply.",
  "lede": "Engagement-weighted volume on r/MachineLearning has tripled in 48 hours, while Bluesky discourse skews 22 points more positive.",
  "publishAt": "2026-05-09T08:42:00Z",
  "readMin": 4,
  "beat": "Governance",
  "signalCount": 12,
  "sourceCount": 5,
  "stub": false
}
Status codes
200OK
401Unauthorized
404No lead story available
GET/v1/stories

Cursor-paginated story list, filterable by topic and entity.

AuthorizationBearer tokenrequired
Query parameters
topicIdstringoptionalFilter by topic ID
entityIdstringoptionalFilter by entity ID
fromISO 8601optionalPublished after this date (inclusive)
toISO 8601optionalPublished before this date (inclusive)
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/stories \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [StoryListItem],
  "nextCursor": "string | null",
  "total": 1247
}
Status codes
200OK
400Invalid filter parameters
401Unauthorized
GET/v1/stories/count

Corpus-wide story count with the same filters as the list.

AuthorizationBearer tokenrequired
Query parameters
topicIdstringoptionalFilter by topic ID
entityIdstringoptionalFilter by entity ID
curl
$ curl https://app.aidran.ai/v1/stories/count \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{ "count": 1247 }
Status codes
200OK
401Unauthorized
GET/v1/stories/by-slug/{slug}

Story detail by canonical slug.

AuthorizationBearer tokenrequired
Path parameters
slugstringrequiredCanonical story slug — e.g. sentiment-diverges-reddit-bluesky
curl
$ curl https://app.aidran.ai/v1/stories/by-slug/{slug} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "s_lead_4f2a",
  "slug": "sentiment-diverges-reddit-bluesky",
  "headline": "Sentiment on AI regulation diverges sharply.",
  "lede": "...",
  "body": "Full AI-generated story body text...",
  "publishAt": "2026-05-09T08:42:00Z",
  "beat": "Governance",
  "versionChain": ["s_lead_4f2a", "s_prev_3e1b"]
}
Status codes
200OK
301Redirected to canonical slug
401Unauthorized
404Story not found
GET/v1/stories/by-topic/{topicId}

Stories that belong to a topic.

AuthorizationBearer tokenrequired
Path parameters
topicIdstring (uuid)requiredTopic ID
Query parameters
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/stories/by-topic/{topicId} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{ "items": [StoryListItem], "nextCursor": null, "total": 42 }
Status codes
200OK
401Unauthorized
404Topic not found
GET/v1/stories/by-entity/{entityId}

Stories that reference an entity.

AuthorizationBearer tokenrequired
Path parameters
entityIdstring (uuid)requiredEntity ID
Query parameters
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/stories/by-entity/{entityId} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{ "items": [StoryListItem], "nextCursor": null, "total": 17 }
Status codes
200OK
401Unauthorized
404Entity not found
GET/v1/stories/{id}

Story detail by ID with full body, citations, and version chain.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredStory ID
curl
$ curl https://app.aidran.ai/v1/stories/{id} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "s_lead_4f2a",
  "slug": "sentiment-diverges-reddit-bluesky",
  "headline": "Sentiment on AI regulation diverges sharply.",
  "lede": "Engagement-weighted volume on r/MachineLearning...",
  "body": "Full AI-generated story body...",
  "citations": [
    { "recordId": "r_2611_0c41", "confidence": 0.94, "inferred": false }
  ],
  "publishAt": "2026-05-09T08:42:00Z",
  "beat": "Governance",
  "readMin": 4,
  "versionChain": ["s_lead_4f2a", "s_prev_3e1b"]
}
Status codes
200OK
401Unauthorized
404Story not found
GET/v1/stories/{id}/versions

Story version chain.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredStory ID
curl
$ curl https://app.aidran.ai/v1/stories/{id}/versions \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "storyId": "s_lead_4f2a",
  "versions": [
    { "id": "s_lead_4f2a", "generatedAt": "2026-05-09T08:42:00Z", "isCurrent": true },
    { "id": "s_prev_3e1b", "generatedAt": "2026-05-08T14:10:00Z", "isCurrent": false }
  ]
}
Status codes
200OK
401Unauthorized
404Story not found
GET/v1/stories/{id}/sources

Corpus records and external citations used as evidence.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredStory ID
curl
$ curl https://app.aidran.ai/v1/stories/{id}/sources \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "storyId": "s_lead_4f2a",
  "sources": [
    {
      "recordId": "r_2611_0c41",
      "kind": "reddit",
      "title": "On post-deployment monitoring...",
      "url": "https://reddit.com/...",
      "sentimentScore": -0.34,
      "inferred": false,
      "confidence": 0.94,
      "credibilityScore": 0.82
    }
  ],
  "externalCitations": [
    {
      "url": "https://arxiv.org/abs/2405.01234",
      "title": "Measuring language model alignment..."
    }
  ]
}
Status codes
200OK
401Unauthorized
404Story not found

Signals

σ-thresholded novelty, velocity, and divergence detections.
4 endpoints
GET/v1/signals

Open and recently-resolved signals, filterable by kind and severity.

AuthorizationBearer tokenrequired
Query parameters
kindstringoptionalSignal type. One of: novelty · velocity · divergence
severitystringoptionalSeverity level. One of: high · medium · low
statusstringoptionalSignal state. One of: open · resolved
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/signals \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "id": "sig_div_9a3b",
      "kind": "divergence",
      "severity": "high",
      "sigmaScore": 3.4,
      "status": "open",
      "detectedAt": "2026-05-09T08:42:00Z"
    }
  ],
  "nextCursor": null,
  "total": 14
}
Status codes
200OK
401Unauthorized
GET/v1/signals/feed

Signal window for the front-page feed.

AuthorizationBearer tokenrequired
Query parameters
limitintegeroptionalDefault 10 · max 50
curl
$ curl https://app.aidran.ai/v1/signals/feed \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [SignalFeedItem],
  "generatedAt": "2026-05-09T08:42:00Z"
}
Status codes
200OK
401Unauthorized
GET/v1/signals/{id}

Signal detail with full evidence chain.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredSignal ID
curl
$ curl https://app.aidran.ai/v1/signals/{id} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "sig_div_9a3b",
  "kind": "divergence",
  "severity": "high",
  "sigmaScore": 3.4,
  "status": "open",
  "detectedAt": "2026-05-09T08:42:00Z",
  "sourceA": "reddit",
  "sourceB": "bluesky",
  "divergencePoints": 22.3,
  "summary": "Cross-platform sentiment divergence on EU AI Act regulation..."
}
Status codes
200OK
401Unauthorized
404Signal not found
GET/v1/signals/{id}/evidence

Records, entities, topics, and stories cited as evidence.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredSignal ID
curl
$ curl https://app.aidran.ai/v1/signals/{id}/evidence \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "signalId": "sig_div_9a3b",
  "records": [
    { "id": "r_2611_0c41", "source": "reddit", "sentimentScore": -0.34 }
  ],
  "entities": [
    { "id": "entity_eu_ai_act_7", "name": "EU AI Act", "type": "concept" }
  ],
  "topics": [
    { "id": "topic_governance_4a1b", "label": "Governance" }
  ],
  "stories": [
    { "id": "s_lead_4f2a", "headline": "Sentiment diverges sharply..." }
  ]
}
Status codes
200OK
401Unauthorized
404Signal not found

Topics

Algorithmically-clustered discourse themes mapped to editorial beats.
2 endpoints
GET/v1/topics

Topic catalogue with record counts and last-activity timestamps.

AuthorizationBearer tokenrequired
Query parameters
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/topics \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "id": "topic_governance_4a1b",
      "slug": "governance",
      "label": "Governance",
      "recordCount": 12841,
      "lastActivity": "2026-05-09T08:42:00Z"
    }
  ],
  "nextCursor": null,
  "total": 47
}
Status codes
200OK
401Unauthorized
GET/v1/topics/{id}

Topic detail with keywords and sample records.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredTopic ID
curl
$ curl https://app.aidran.ai/v1/topics/{id} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "topic_governance_4a1b",
  "slug": "governance",
  "label": "Governance",
  "recordCount": 12841,
  "lastActivity": "2026-05-09T08:42:00Z",
  "keywords": ["regulation", "EU AI Act", "policy", "oversight"],
  "storyCount": 42
}
Status codes
200OK
401Unauthorized
404Topic not found

Entities

Named people, organisations, products, and concepts with mention analytics.
5 endpoints
GET/v1/entities

Entity list: one strongest public row per canonical slug, with lede, mention counts, source mix, and growth factors.

AuthorizationBearer tokenrequired
Query parameters
typestringoptionalEntity type. One of: person · org · product · place · concept
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/entities \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "id": "entity_openai_42",
      "name": "OpenAI",
      "type": "organization",
      "slug": "openai",
      "canonicalPath": "/entities/openai",
      "lede": "OpenAI is an organization tracked in 4,821 mentions, including 847 in the last 24 hours across reddit and bluesky.",
      "mentionCount": 4821,
      "growthFactor": 2.3,
      "recentMentions": 847
    }
  ],
  "nextCursor": null,
  "total": 1204
}
Status codes
200OK
401Unauthorized
GET/v1/entities/{id}

Entity detail: sentiment trend, prominence rank, story arcs.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredEntity ID
curl
$ curl https://app.aidran.ai/v1/entities/{id} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "entity_openai_42",
  "name": "OpenAI",
  "type": "organization",
  "slug": "openai",
  "canonicalPath": "/entities/openai",
  "lede": "OpenAI is an organization tracked in 4,821 mentions, including 847 in the last 24 hours across reddit and bluesky.",
  "mentionCount": 4821,
  "recentMentions": 847,
  "growthFactor": 2.3,
  "baselineMentions": 368,
  "sentimentDistribution": {
    "positive": 1203, "neutral": 2814,
    "negative": 804,  "unknown": 0
  },
  "sentimentTrend": [
    { "weekStart": "2026-05-05", "avgScore": -0.18, "sampleSize": 311 }
  ],
  "prominenceRank": { "withinType": 98, "sampleSize": 1204 },
  "noveltyActive": true,
  "sourceDiversity": { "distinctSources": 6, "herfindahlIndex": 2140 }
}
Status codes
200OK
401Unauthorized
404Entity not found
GET/v1/entities/by-slug/{entityKey}

Resolve a bare canonical slug or legacy numeric/trailing-id key.

AuthorizationBearer tokenrequired
Path parameters
entityKeystringrequiredBare canonical slug (openai); legacy numeric and trailing-id keys still resolve for redirects
curl
$ curl https://app.aidran.ai/v1/entities/by-slug/{entityKey} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
// Same shape as GET /v1/entities/{id}
Status codes
200OK
301Redirected to canonical key
401Unauthorized
404Entity not found
GET/v1/entities/sitemap-pages

Chunk counts and max lastmod for sitemap generation.

AuthorizationBearer tokenrequired
curl
$ curl https://app.aidran.ai/v1/entities/sitemap-pages \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "pages": [
    { "page": 1, "count": 500, "maxUpdatedAt": "2026-05-09T08:42:00Z" },
    { "page": 2, "count": 500, "maxUpdatedAt": "2026-05-08T12:00:00Z" }
  ],
  "total": 1204
}
Status codes
200OK
401Unauthorized
GET/v1/entities/slugs

Paginated bare canonical entity URL drain for sitemaps.

AuthorizationBearer tokenrequired
Query parameters
limitintegeroptionalDefault 500 (sitemap batch size)
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/entities/slugs \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    { "id": "entity_openai_42", "slug": "openai",
      "canonicalPath": "/entities/openai" }
  ],
  "nextCursor": "eyJ..."
}
Status codes
200OK
401Unauthorized

Sources

Per-source ingestion volumes and health for configured source kinds.
1 endpoint
GET/v1/sources

Per-source ingestion volume and health for configured source kinds.

AuthorizationBearer tokenrequired
curl
$ curl https://app.aidran.ai/v1/sources \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "sources": [
    { "id": "reddit",     "recordCount": 142841, "lastIngestedAt": "2026-05-09T08:41:00Z", "healthy": true },
    { "id": "bluesky",    "recordCount": 98204,  "lastIngestedAt": "2026-05-09T08:40:00Z", "healthy": true },
    { "id": "arxiv",      "recordCount": 41022,  "lastIngestedAt": "2026-05-09T07:30:00Z", "healthy": true },
    { "id": "hackernews", "recordCount": 38471,  "lastIngestedAt": "2026-05-09T08:39:00Z", "healthy": true },
    { "id": "youtube",    "recordCount": 27904,  "lastIngestedAt": "2026-05-09T08:35:00Z", "healthy": true },
    { "id": "google_news","recordCount": 86122,  "lastIngestedAt": "2026-05-09T08:42:00Z", "healthy": true },
    { "id": "huggingface","recordCount": 620,    "lastIngestedAt": "2026-05-09T08:12:00Z", "healthy": true },
    { "id": "twitter",    "recordCount": 51578,  "lastIngestedAt": "2026-05-09T08:41:00Z", "healthy": true }
  ]
}
Status codes
200OK
401Unauthorized

Stats

Corpus-level timelines, sentiment distributions, and trending entities.
6 endpoints
GET/v1/stats/global/timeline

Global record volume timeline across all sources.

AuthorizationBearer tokenrequired
Query parameters
daysintegeroptionalNumber of days. Default 30 · max 365
curl
$ curl https://app.aidran.ai/v1/stats/global/timeline \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "timeline": [
    {
      "date": "2026-05-09",
      "recordCount": 8341,
      "sources": {
        "reddit": 2841, "bluesky": 1204,
        "arxiv": 442,   "hackernews": 1102
      }
    }
  ]
}
Status codes
200OK
401Unauthorized
GET/v1/stats/sources/{id}/timeline

Activity timeline for a single source.

AuthorizationBearer tokenrequired
Path parameters
idstringrequiredSource ID — reddit · bluesky · arxiv · hackernews · youtube · google_news · exa · webset · huggingface · twitter
Query parameters
daysintegeroptionalDefault 30 · max 365
curl
$ curl https://app.aidran.ai/v1/stats/sources/{id}/timeline \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "sourceId": "reddit",
  "timeline": [
    { "date": "2026-05-09", "recordCount": 2841 },
    { "date": "2026-05-08", "recordCount": 2600 }
  ]
}
Status codes
200OK
401Unauthorized
404Unknown source ID
GET/v1/stats/sentiment/timeline

Sentiment timeline (live 30-day window; accepts up to 365).

AuthorizationBearer tokenrequired
Query parameters
daysintegeroptionalDefault 7 · max 365 (live aggregate bounded to 30 days)
curl
$ curl https://app.aidran.ai/v1/stats/sentiment/timeline \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "timeline": [
    {
      "date": "2026-05-09",
      "avgScore": -0.08,
      "sources": {
        "reddit": -0.34, "bluesky": 0.14, "arxiv": 0.02
      }
    }
  ]
}
Status codes
200OK
401Unauthorized
GET/v1/stats/entities/trending

Entities ranked by growth factor over baseline.

AuthorizationBearer tokenrequired
Query parameters
nintegeroptionalNumber of entities. Default 10 · max 50
curl
$ curl https://app.aidran.ai/v1/stats/entities/trending \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "entities": [
    {
      "id": "entity_openai_42",
      "name": "OpenAI",
      "type": "organization",
      "mentionCount": 4821,
      "growthFactor": 2.3,
      "recentMentions": 847,
      "canonicalPath": "/entities/openai"
    }
  ]
}
Status codes
200OK
401Unauthorized
GET/v1/stats/topics/distribution

Topic share distribution across the corpus.

AuthorizationBearer tokenrequired
curl
$ curl https://app.aidran.ai/v1/stats/topics/distribution \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "topics": [
    { "id": "topic_governance_4a1b", "label": "Governance",
      "share": 0.174, "recordCount": 12841 },
    { "id": "topic_research_8b2c", "label": "Research",
      "share": 0.128, "recordCount": 9422 }
  ],
  "totalRecords": 73840
}
Status codes
200OK
401Unauthorized
GET/v1/stats/topics/{id}/timeline

Activity timeline for a specific topic.

AuthorizationBearer tokenrequired
Path parameters
idstring (uuid)requiredTopic ID
Query parameters
daysintegeroptionalDefault 30 · max 365
curl
$ curl https://app.aidran.ai/v1/stats/topics/{id}/timeline \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "topicId": "topic_governance_4a1b",
  "timeline": [
    { "date": "2026-05-09", "recordCount": 421, "share": 0.18 }
  ]
}
Status codes
200OK
401Unauthorized
404Topic not found

Arcs

Named temporal threads grouping related stories into editorial arcs.
2 endpoints
GET/v1/arcs

List story arcs with member story counts and status.

AuthorizationBearer tokenrequired
Query parameters
limitintegeroptionalDefault 20 · max 100
cursorstringoptionalPagination cursor
curl
$ curl https://app.aidran.ai/v1/arcs \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "items": [
    {
      "id": "arc_eu_ai_act_8c2d",
      "slug": "eu-ai-act-timeline",
      "title": "EU AI Act timeline",
      "arcStatus": "active",
      "storyCount": 14,
      "lastUpdatedAt": "2026-05-09T08:42:00Z"
    }
  ],
  "nextCursor": null,
  "total": 8
}
Status codes
200OK
401Unauthorized
GET/v1/arcs/{slug}

Arc detail by slug with member stories.

AuthorizationBearer tokenrequired
Path parameters
slugstringrequiredArc slug — e.g. eu-ai-act-timeline
curl
$ curl https://app.aidran.ai/v1/arcs/{slug} \
  -H 'Authorization: Bearer YOUR_KEY'
Response — 200 OK
{
  "id": "arc_eu_ai_act_8c2d",
  "slug": "eu-ai-act-timeline",
  "title": "EU AI Act timeline",
  "arcStatus": "active",
  "storyCount": 14,
  "lastUpdatedAt": "2026-05-09T08:42:00Z",
  "stories": [
    { "id": "s_lead_4f2a",
      "headline": "Sentiment diverges sharply...",
      "publishAt": "2026-05-09T08:42:00Z" }
  ]
}
Status codes
200OK
401Unauthorized
404Arc not found

Stream

Server-sent event streams for live signal updates.
2 endpoints
Content-Type: text/event-stream · Heartbeat every 30 s · Reconnect with Last-Event-ID
GET/v1/stream/signals

Active SSE stream of new and updated signals. Heartbeat every 30s.

AuthorizationBearer tokenrequired
curl
$ curl -N \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Accept: text/event-stream' \
  https://app.aidran.ai/v1/stream/signals
Response — 200 OK
// Server-Sent Events — connect with: Accept: text/event-stream
 
event: signal
data: {
  "id": "sig_vel_2c1a",
  "kind": "velocity",
  "severity": "high",
  "sigmaScore": 2.8,
  "detectedAt": "2026-05-09T08:42:00Z"
}
 
event: heartbeat
data: { "ts": "2026-05-09T08:42:00Z" }
 
// Heartbeat fires every 30 seconds to keep connections alive.
// Reconnect with Last-Event-ID to resume from a signal ID.
Status codes
200text/event-stream connection established
401Unauthorized
GET/v1/stream/stories501

Reserved story SSE stream — returns 501.

AuthorizationBearer tokenrequired
curl
# Not implemented — returns 501
Response — 200 OK
{ "error": "Not implemented" }
Status codes
501Not Implemented — reserved for a future release