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

501not implemented

Records

Discourse records ingested from public source kinds.

5 endpoints

GET/v1/recordsTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`source`	string	optional	Platform. One of: reddit · bluesky · arxiv · hackernews · youtube · google_news · exa · webset · huggingface · twitter
`sentiment`	string	optional	Sentiment label. One of: positive · neutral · negative
`from`	ISO 8601	optional	Time window start (inclusive)
`to`	ISO 8601	optional	Time window end (inclusive)
`limit`	integer	optional	Items per page. Default 20 · max 100
`cursor`	string	optional	Opaque 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

Code	Message
`200`	OK — items array with nextCursor
`400`	Invalid filter parameters
`401`	Unauthorized

GET/v1/records/{id}Try it

Single record with full content and source metadata.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Record 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Record not found

GET/v1/records/{id}/embeddingTry it

512-dim voyage-4-lite embedding vector.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Record 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Record not found

GET/v1/records/{id}/entitiesTry it

Entity mentions attached to the record.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Record ID

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Record not found

GET/v1/records/{id}/topicsTry it

Topic assignments for the record.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Record 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Record not found

Stories

AI-generated editorial stories with citations and provenance.

9 endpoints

GET/v1/stories/leadTry it

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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	No lead story available

GET/v1/storiesTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`topicId`	string	optional	Filter by topic ID
`entityId`	string	optional	Filter by entity ID
`from`	ISO 8601	optional	Published after this date (inclusive)
`to`	ISO 8601	optional	Published before this date (inclusive)
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`400`	Invalid filter parameters
`401`	Unauthorized

GET/v1/stories/countTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`topicId`	string	optional	Filter by topic ID
`entityId`	string	optional	Filter by entity ID

curl

$ curl https://app.aidran.ai/v1/stories/count \
  -H 'Authorization: Bearer YOUR_KEY'

Response — 200 OK

{ "count": 1247 }

Status codes

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/stories/by-slug/{slug}Try it

Story detail by canonical slug.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`slug`	string	required	Canonical 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

Code	Message
`200`	OK
`301`	Redirected to canonical slug
`401`	Unauthorized
`404`	Story not found

GET/v1/stories/by-topic/{topicId}Try it

Stories that belong to a topic.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`topicId`	string (uuid)	required	Topic ID

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Topic not found

GET/v1/stories/by-entity/{entityId}Try it

Stories that reference an entity.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`entityId`	string (uuid)	required	Entity ID

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Entity not found

GET/v1/stories/{id}Try it

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

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Story 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Story not found

GET/v1/stories/{id}/versionsTry it

Story version chain.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Story 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Story not found

GET/v1/stories/{id}/sourcesTry it

Corpus records and external citations used as evidence.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Story 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Story not found

Signals

σ-thresholded novelty, velocity, and divergence detections.

4 endpoints

GET/v1/signalsTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`kind`	string	optional	Signal type. One of: novelty · velocity · divergence
`severity`	string	optional	Severity level. One of: high · medium · low
`status`	string	optional	Signal state. One of: open · resolved
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/signals/feedTry it

Signal window for the front-page feed.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/signals/{id}Try it

Signal detail with full evidence chain.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Signal 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Signal not found

GET/v1/signals/{id}/evidenceTry it

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

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Signal 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Signal not found

Topics

Algorithmically-clustered discourse themes mapped to editorial beats.

2 endpoints

GET/v1/topicsTry it

Topic catalogue with record counts and last-activity timestamps.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/topics/{id}Try it

Topic detail with keywords and sample records.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Topic 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Topic not found

Entities

Named people, organisations, products, and concepts with mention analytics.

5 endpoints

GET/v1/entitiesTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`type`	string	optional	Entity type. One of: person · org · product · place · concept
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/entities/{id}Try it

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

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Entity 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Entity not found

GET/v1/entities/by-slug/{entityKey}Try it

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

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`entityKey`	string	required	Bare 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

Code	Message
`200`	OK
`301`	Redirected to canonical key
`401`	Unauthorized
`404`	Entity not found

GET/v1/entities/sitemap-pagesTry it

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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/entities/slugsTry it

Paginated bare canonical entity URL drain for sitemaps.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 500 (sitemap batch size)
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized

Sources

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

1 endpoint

GET/v1/sourcesTry it

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

Code	Message
`200`	OK
`401`	Unauthorized

Search

Hybrid vector + keyword search across records, stories, entities, and topics.

4 endpoints

POST/v1/searchTry it

Full corpus search. Returns typed hits with browseable hrefs.

AuthorizationBearer tokenrequired

Request body — application/json

{
  "q": "model collapse",
  "limit": 10,
  "types": ["story", "entity", "topic", "record"]
}
// types — optional, all types searched by default

curl

$ curl -X POST https://app.aidran.ai/v1/search \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q":"..."}'

Response — 200 OK

{
  "hits": [
    {
      "type": "story",
      "score": 0.94,
      "id": "s_lead_4f2a",
      "headline": "Sentiment diverges sharply...",
      "href": "/story/sentiment-diverges-reddit-bluesky"
    },
    {
      "type": "entity",
      "score": 0.81,
      "id": "entity_openai_42",
      "name": "OpenAI",
      "href": "/entities/openai"
    }
  ],
  "total": 47,
  "query": "model collapse"
}

Status codes

Code	Message
`200`	OK
`400`	Invalid request body
`401`	Unauthorized

GET/v1/search/quickTry it

Lightweight autocomplete for topics, entities, stories, and records.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`q`	string	required	Search query (min 2 characters)
`limit`	integer	optional	Default 8 · max 20

curl

$ curl https://app.aidran.ai/v1/search/quick \
  -H 'Authorization: Bearer YOUR_KEY'

Response — 200 OK

{
  "results": [
    { "type": "entity", "name": "OpenAI",
      "href": "/entities/openai" },
    { "type": "topic",  "name": "Governance",
      "href": "/beats/governance" },
    { "type": "story",
      "headline": "Sentiment diverges sharply...",
      "href": "/story/sentiment-diverges-reddit-bluesky" }
  ]
}

Status codes

Code	Message
`200`	OK
`401`	Unauthorized

POST/v1/search/similarTry it

Similarity search by record ID or raw embedding vector.

AuthorizationBearer tokenrequired

Request body — application/json

{
  // Provide exactly one of:
  "recordId": "r_2611_0c41",
  // OR
  "embedding": [0.021, -0.143, 0.087, "..."],
  "limit": 10
}

curl

$ curl -X POST https://app.aidran.ai/v1/search/similar \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q":"..."}'

Response — 200 OK

{
  "hits": [
    { "id": "r_2611_0c43", "source": "bluesky",
      "score": 0.91, "title": "..." }
  ]
}

Status codes

Code	Message
`200`	OK
`400`	Provide exactly one of recordId or embedding
`401`	Unauthorized

POST/v1/search/embed501

Not implemented — returns 501.

AuthorizationBearer tokenrequired

curl

# Not implemented — returns 501

Response — 200 OK

{ "error": "Not implemented" }

Status codes

Code	Message
`501`	Not Implemented

Stats

Corpus-level timelines, sentiment distributions, and trending entities.

6 endpoints

GET/v1/stats/global/timelineTry it

Global record volume timeline across all sources.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`days`	integer	optional	Number 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/stats/sources/{id}/timelineTry it

Activity timeline for a single source.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string	required	Source ID — reddit · bluesky · arxiv · hackernews · youtube · google_news · exa · webset · huggingface · twitter

Query parameters

Name	Type	Req	Description
`days`	integer	optional	Default 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Unknown source ID

GET/v1/stats/sentiment/timelineTry it

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

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`days`	integer	optional	Default 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/stats/entities/trendingTry it

Entities ranked by growth factor over baseline.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`n`	integer	optional	Number 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/stats/topics/distributionTry it

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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/stats/topics/{id}/timelineTry it

Activity timeline for a specific topic.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`id`	string (uuid)	required	Topic ID

Query parameters

Name	Type	Req	Description
`days`	integer	optional	Default 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Topic not found

Arcs

Named temporal threads grouping related stories into editorial arcs.

2 endpoints

GET/v1/arcsTry it

List story arcs with member story counts and status.

AuthorizationBearer tokenrequired

Query parameters

Name	Type	Req	Description
`limit`	integer	optional	Default 20 · max 100
`cursor`	string	optional	Pagination 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

Code	Message
`200`	OK
`401`	Unauthorized

GET/v1/arcs/{slug}Try it

Arc detail by slug with member stories.

AuthorizationBearer tokenrequired

Path parameters

Name	Type	Req	Description
`slug`	string	required	Arc 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

Code	Message
`200`	OK
`401`	Unauthorized
`404`	Arc 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/signalsTry it

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

Code	Message
`200`	text/event-stream connection established
`401`	Unauthorized

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

Code	Message
`501`	Not Implemented — reserved for a future release