Reference

API Reference

Programmatic access to AIDRAN's discourse data. All endpoints return JSON and are available under /api/v1.

Authentication

All endpoints require authentication. Include your API key using either the x-api-key header or the Authorization: Bearer <key> header.

curl -H "x-api-key: YOUR_KEY" \
  https://aidran.ai/api/v1/topics

Using the Authorization header:

curl -H "Authorization: Bearer YOUR_KEY" \
  https://aidran.ai/api/v1/topics

Base URL

https://aidran.ai/api/v1

All endpoint paths below are relative to this base URL. Responses are JSON with Content-Type: application/json.

Endpoints

GET/api/v1/topics

Returns all active editorial topics with metadata including display names, descriptions, categories, keywords, and tracked subreddits.

Query Parameters

Parameter	Type	Description
`active`	boolean	Filter by active status. Defaults to true.

Response: Returns { topics: [...], count: number }

GET/api/v1/discourse

Paginated access to discourse records with filtering by source platform, topic, and date range. Returns full record data including analysis results.

Query Parameters

Parameter	Type	Description
`source`	string	Filter by platform: "reddit", "bluesky", or "gdelt".
`topic`	string	Filter by topic slug.
`since`	ISO 8601	Records captured after this date.
`until`	ISO 8601	Records captured before this date.
`limit`	integer	Results per page. Default 50, max 100.
`offset`	integer	Pagination offset. Default 0.

Response: Returns { data: [...], pagination: { total, limit, offset, hasMore } }

GET/api/v1/search

Search discourse records using Voyage AI embeddings and pgvector. Returns results ranked by semantic similarity to your query.

Query Parameters

Parameter	Type	Description
`q`required	string	Search query. Max 500 characters.
`source`	string	Filter by platform: "reddit", "bluesky", or "gdelt".
`topic`	string	Filter by topic slug.
`days`	integer	Limit to records from the last N days.
`limit`	integer	Max results. Default 20, max 50.

GET/api/v1/signals

Signals detected by the analysis pipeline: volume spikes, sentiment shifts, emerging narratives, and cross-platform divergences.

Query Parameters

Parameter	Type	Description
`topic`	string	Filter by topic slug.
`severity`	string	Filter by severity level.
`since`	ISO 8601	Signals detected after this date.
`limit`	integer	Results per page. Default 50, max 100.
`offset`	integer	Pagination offset. Default 0.

Response: Returns { data: [...], pagination: { total, limit, offset, hasMore } }

GET/api/v1/entities

Named entities extracted from discourse analysis, aggregated by mention count. Returns the most frequently mentioned entities across tracked records.

Query Parameters

Parameter	Type	Description
`topic`	string	Filter by topic slug. Defaults to all topics.
`since`	ISO 8601	Aggregate from this date. Defaults to 7 days ago.
`limit`	integer	Max entities returned. Default 50, max 200.

Response: Returns { data: [{ name, mentions, types }], count, params }

GET/api/v1/clusters

Narrative clusters from the latest clustering analysis. Groups related discourse into coherent narrative threads with labels and top terms.

Query Parameters

Parameter	Type	Description
`topic`	string	Filter by topic slug.
`limit`	integer	Max clusters returned. Default 50, max 100.

Response: Returns { data: [...], count: number }

GET/api/v1/trends

Daily discourse volume counts for a specific topic, along with external trend signals from sources like Google Trends.

Query Parameters

Parameter	Type	Description
`topic`required	string	Topic slug. Required.
`days`	integer	Number of days to look back. Default 30.

Response: Returns { topic, days, volume: [{ day, count }], externalTrends: [...] }

Error Responses

Errors return a JSON object with an error field describing the issue.

// 400 Bad Request — missing required parameter
{ "error": "q parameter is required" }

// 401 Unauthorized — missing or invalid API key
{ "error": "Invalid or missing API key" }

// 503 Service Unavailable — API keys not configured
{ "error": "API access not configured" }

// 500 Internal Server Error
{ "error": "Search failed" }

Status	Meaning
200	Success. Response body contains the requested data.
400	Bad request. A required parameter is missing or invalid.
401	Unauthorized. API key is missing or invalid.
500	Internal error. Try again or contact support.
503	Service unavailable. API keys not yet configured on server.

Request API Access

AIDRAN's API is available to researchers, journalists, and developers working with AI discourse data. To request an API key, reach out with a brief description of your use case.

Request an API Key