Skip to main content

​
API Reference

​
Base URL

https://api.gildea.ai/v1

​
Authentication

All endpoints (except health check) require an X-API-Key header. See Authentication.

​
Endpoints

​
Signals

MethodEndpointDescription
GET/v1/signalsList signals — paginated, filtered
GET/v1/signals/{signal_id}Get signal — full decomposition

​
Entities

MethodEndpointDescription
GET/v1/entitiesList entities — paginated
GET/v1/entities/trendingTrending entities — ranked by trend mode
GET/v1/entities/{name_or_id}Get entity — full profile

​
Themes

MethodEndpointDescription
GET/v1/themesList themes — all themes
GET/v1/themes/{axis}/{label}Get theme — detail with co-occurrences
MethodEndpointDescription
GET/v1/searchSearch — hybrid semantic + keyword

​
System

MethodEndpointDescription
GET/v1/healthHealth check — no auth required
POST/v1/admin/refreshRefresh — admin only

​
Common patterns

  • Pagination: Cursor-based — see Pagination guide
  • Filtering: Most list endpoints accept entity, theme, and q filters
  • Progressive disclosure: Use include=evidence and verification_detail=full for more data
  • Error format: Consistent {"error": {"code", "message", "status"}} envelope