{"openapi":"3.0.3","info":{"title":"Newsradar API","version":"1.0.0","description":"Public read API over an international news corpus. Search articles by keyword (accent-insensitive FTS), filter by newspaper, state, city, country, category, sentiment, news type, and date range.","contact":{"name":"Newsradar","url":"https://newsradar.ai"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://newsradar.ai"}],"security":[{"ApiKeyHeader":[]},{"ApiKeyBearer":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","name":"X-Api-Key","in":"header","description":"API key in the X-Api-Key header. Format: `nr_live_<32 chars>`."},"ApiKeyBearer":{"type":"http","scheme":"bearer","description":"API key as a Bearer token in the Authorization header."},"ApiKeyQuery":{"type":"apiKey","name":"apiKey","in":"query","description":"API key as a query parameter (less preferred; appears in logs)."}},"schemas":{"Article":{"type":"object","description":"A news article. The `url` field is the stable identifier — use it for caching, deduping, and referring to articles. There is no separate `id`.","required":["source","url"],"properties":{"source":{"$ref":"#/components/schemas/Source"},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","description":"Canonical article URL — the article identity."},"publishedAt":{"type":"string","format":"date-time","nullable":true},"newsType":{"type":"string","nullable":true,"enum":["local","national","international",null]},"category":{"type":"string","nullable":true,"description":"English slug. See /v1/categories for the full list.","example":"security"},"sentiment":{"type":"string","nullable":true,"enum":["positive","neutral","negative",null]},"place":{"$ref":"#/components/schemas/Place"},"authors":{"type":"array","items":{"type":"string"},"description":"Ordered author names. Empty array when none recorded."},"content":{"type":"string","nullable":true,"description":"Full article body. Returned by default; opt out with `fields=` projection."},"summary":{"type":"object","nullable":true,"properties":{"en":{"type":"string","nullable":true},"es":{"type":"string","nullable":true}}}}},"Source":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Newspaper slug.","example":"el-universal"},"name":{"type":"string","nullable":true,"example":"el universal"}}},"PlaceRef":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","nullable":true,"description":"Canonical slug. Null when the stored variant is not in the registry (e.g., foreign places, or new variants the AI emitted)."},"name":{"type":"string","description":"Raw stored name as classified for the article."}}},"Place":{"type":"object","description":"Where the article is ABOUT (classified per-article). Different from the newspaper home location. Each sub-array contains 0..N entries: zero if not classified, one for typical single-place articles, multiple for cross-region pieces (the AI sometimes emits \"Sinaloa, Chiapas, Jalisco, Ciudad de Mexico\" for a single article).","required":["states","cities","countries"],"properties":{"states":{"type":"array","items":{"$ref":"#/components/schemas/PlaceRef"},"example":[{"slug":"cdmx","name":"Ciudad de México"}]},"cities":{"type":"array","items":{"$ref":"#/components/schemas/PlaceRef"},"example":[{"slug":"monterrey","name":"Monterrey"}]},"countries":{"type":"array","items":{"$ref":"#/components/schemas/PlaceRef"},"example":[{"slug":"usa","name":"United States"}]}}},"State":{"type":"object","required":["slug","name","country"],"properties":{"slug":{"type":"string","example":"cdmx"},"name":{"type":"string","example":"ciudad de mexico"},"country":{"type":"string","example":"mexico"},"cities":{"type":"array","items":{"$ref":"#/components/schemas/City"}}}},"City":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"monterrey"},"name":{"type":"string","example":"monterrey"}}},"Country":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"mexico"},"name":{"type":"string","example":"mexico"}}},"Newspaper":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"el-universal"},"name":{"type":"string","example":"el universal"},"state":{"type":"string","nullable":true,"example":"cdmx","description":"State slug, or null if the newspaper has no CONST mapping."},"country":{"type":"string","nullable":true,"example":"mexico"}}},"Category":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"security","enum":["columns","culture-and-art","economy-and-finance","education","employment","entertainment","environment","government","health","other","politics","public-works","security","sports","tourism","transportation","urban-development"]},"name":{"type":"string","example":"security"}}},"ErrorResponse":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"string","enum":["error"]},"code":{"type":"string","example":"invalid_sentiment"},"message":{"type":"string"},"retryAfter":{"type":"integer","description":"Present on 429 responses."}}},"BilingualText":{"type":"object","properties":{"en":{"type":"string","nullable":true},"es":{"type":"string","nullable":true}}},"Conference":{"type":"object","description":"A conference (press-conference / broadcast transcript). `id` is the source video id.","required":["id"],"properties":{"id":{"type":"string","example":"dQw4w9WgXcQ"},"title":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"thumbnail":{"type":"string","format":"uri","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"complete":{"type":"boolean"},"summary":{"$ref":"#/components/schemas/BilingualText"},"topics":{"type":"object","description":"Structured topic breakdown (≈10-15 entries), EN/ES. This is the conference summary — each entry has a specific topic, its content, and the timestamp (seconds) where it begins.","properties":{"en":{"type":"array","items":{"$ref":"#/components/schemas/ConferenceTopic"}},"es":{"type":"array","items":{"$ref":"#/components/schemas/ConferenceTopic"}}}},"matches":{"type":"array","description":"Transcript segments containing the search term, with timestamps. Present only when `q` is set.","items":{"$ref":"#/components/schemas/ConferenceSegment"}}}},"ConferenceTopic":{"type":"object","properties":{"topic":{"type":"string","nullable":true},"content":{"type":"string","nullable":true},"timestamp":{"type":"number","nullable":true,"description":"Offset in seconds into the video where this topic begins."}}},"ConferenceSegment":{"type":"object","properties":{"text":{"type":"string","nullable":true},"offset":{"type":"number","nullable":true},"duration":{"type":"number","nullable":true},"lang":{"type":"string","nullable":true}}},"ConferenceDetail":{"type":"object","description":"A conference with full transcript text, topics, and timed segments.","required":["id"],"properties":{"id":{"type":"string","example":"dQw4w9WgXcQ"},"title":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true},"thumbnail":{"type":"string","format":"uri","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"complete":{"type":"boolean"},"summary":{"$ref":"#/components/schemas/BilingualText"},"transcript":{"type":"string"},"topics":{"type":"object","properties":{"en":{"type":"array","items":{"$ref":"#/components/schemas/ConferenceTopic"}},"es":{"type":"array","items":{"$ref":"#/components/schemas/ConferenceTopic"}}}},"segments":{"type":"array","items":{"$ref":"#/components/schemas/ConferenceSegment"}}}},"FrontPagePlace":{"type":"object","description":"Where the front page / article is from (the newspaper home location).","properties":{"country":{"$ref":"#/components/schemas/PlaceRef"},"state":{"$ref":"#/components/schemas/PlaceRef"},"city":{"$ref":"#/components/schemas/PlaceRef"}}},"FrontPageArticle":{"type":"object","description":"One article summarized from a front page.","properties":{"title":{"$ref":"#/components/schemas/BilingualText"},"synopsis":{"$ref":"#/components/schemas/BilingualText"},"sentiment":{"type":"string","nullable":true,"enum":["positive","neutral","negative",null]},"category":{"type":"string","nullable":true,"example":"security"},"place":{"$ref":"#/components/schemas/FrontPagePlace"}}},"FrontPage":{"type":"object","description":"A newspaper front page for a given day.","required":["id","newspaper"],"properties":{"id":{"type":"string"},"newspaper":{"type":"object","properties":{"slug":{"type":"string","example":"reforma"},"name":{"type":"string","example":"reforma"}}},"date":{"type":"string","format":"date-time","nullable":true},"imageUrl":{"type":"string","format":"uri","nullable":true},"place":{"$ref":"#/components/schemas/FrontPagePlace"},"categoriesMentioned":{"type":"array","items":{"type":"string"}},"analysis":{"$ref":"#/components/schemas/BilingualText"},"articles":{"type":"array","items":{"$ref":"#/components/schemas/FrontPageArticle"}}}}}},"paths":{"/v1/health":{"get":{"summary":"Liveness check","description":"Unauthenticated. Returns 200 when the API + database are reachable, 503 if the DB ping fails.","security":[],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"db":{"type":"string","enum":["ok"]},"dbLatencyMs":{"type":"integer","nullable":true},"timestamp":{"type":"string","format":"date-time"},"responseTimeMs":{"type":"integer"}}}}}},"503":{"description":"Degraded — DB ping failed"}}}},"/v1/articles":{"get":{"summary":"Search articles","description":"Search and filter articles. Returns a paginated list ordered by publishedAt (default) or relevancy (when `q` is provided).","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text search (Spanish accent-insensitive).","example":"sheinbaum"},{"name":"newspapers","in":"query","schema":{"type":"string"},"description":"Comma-separated newspaper slugs. Prefix with `-` to exclude.","example":"el-universal,-reforma"},{"name":"article_state","in":"query","schema":{"type":"string"},"description":"CSV of state slugs where the article is ABOUT (topic).","example":"cdmx,jalisco"},{"name":"state","in":"query","schema":{"type":"string"},"description":"Back-compat alias for `article_state`.","deprecated":true,"example":"cdmx"},{"name":"article_city","in":"query","schema":{"type":"string"},"description":"CSV of city slugs. Optionally scoped by article_state.","example":"monterrey"},{"name":"newspaper_state","in":"query","schema":{"type":"string"},"description":"CSV of state slugs where the newspaper is BASED.","example":"cdmx"},{"name":"country","in":"query","schema":{"type":"string"},"description":"CSV of country slugs.","example":"mexico,usa"},{"name":"category","in":"query","schema":{"type":"string","enum":["columns","culture-and-art","economy-and-finance","education","employment","entertainment","environment","government","health","other","politics","public-works","security","sports","tourism","transportation","urban-development"]},"description":"CSV of category slugs (English).","example":"security"},{"name":"sentiment","in":"query","schema":{"type":"string","enum":["positive","neutral","negative"]},"example":"positive"},{"name":"news_type","in":"query","schema":{"type":"string","enum":["local","national","international"]},"example":"local"},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date or YYYY-MM-DD. Default: 30 days ago.","example":"2026-05-01"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date or YYYY-MM-DD. Default: now.","example":"2026-05-22"},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["publishedAt","relevancy"],"default":"publishedAt"},"example":"relevancy"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"CSV of fields to include, or `*` for all. Defaults to a generous set including content + summary.","example":"url,title,publishedAt,summary"},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Alternative to cursor. Capped at 100.","example":2},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response. Use with sort_by=publishedAt only."}],"responses":{"200":{"description":"Paginated article list","content":{"application/json":{"schema":{"type":"object","required":["status","totalResults","articles"],"properties":{"status":{"type":"string","enum":["ok"]},"totalResults":{"type":"integer"},"articles":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"nextCursor":{"type":"string","nullable":true},"suggestions":{"type":"object","description":"Present only when totalResults is 0 and a slug filter likely had a typo. Maps each affected filter to close slug suggestions (\"did you mean?\").","additionalProperties":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","example":"sinaloa"},"name":{"type":"string","example":"sinaloa"}}}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/stories":{"get":{"summary":"List story clusters","description":"Deduplicated multi-source story clusters from the persistent record store. Two modes: the date-range ARCHIVE (default) returns stories whose active period overlaps from/to, newest-first by first-detected, keyset-paginated via cursor; the STORIES-OF-TODAY view (window=today&rank=top) returns the current-day set ranked by recency-decayed source volume (the homepage stories). Supersedes the retired /v1/story-clusters.","parameters":[{"name":"window","in":"query","schema":{"type":"string","enum":["today"]},"description":"window=today returns stories active in the current calendar day (the homepage set). Omit for the from/to date-range archive.","example":"today"},{"name":"rank","in":"query","schema":{"type":"string","enum":["top"]},"description":"rank=top orders by recency-decayed source volume (top stories now). Omit for chronological order (newest-first by first-detected).","example":"top"},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date or YYYY-MM-DD. Default: 30 days ago.","example":"2026-06-14"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date or YYYY-MM-DD. Default: now.","example":"2026-06-14"},{"name":"state","in":"query","schema":{"type":"string"},"description":"State slug; only stories covering that state.","example":"jalisco"},{"name":"category","in":"query","schema":{"type":"string","enum":["columns","culture-and-art","economy-and-finance","education","employment","entertainment","environment","government","health","other","politics","public-works","security","sports","tourism","transportation","urban-development"]},"description":"CSV of category slugs (English).","example":"security"},{"name":"qualified","in":"query","schema":{"type":"boolean","default":true},"description":"When true (default), only corroborated stories (3+ sources or 5+ articles).","example":true},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":12},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response. Use with sort_by=publishedAt only."}],"responses":{"200":{"description":"A list of story clusters.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/newspapers":{"get":{"summary":"List all newspapers","responses":{"200":{"description":"Newspaper list","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"totalResults":{"type":"integer"},"newspapers":{"type":"array","items":{"$ref":"#/components/schemas/Newspaper"}}}}}}}}}},"/v1/newspapers/{slug}":{"get":{"summary":"Get one newspaper by slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Newspaper details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"newspaper":{"$ref":"#/components/schemas/Newspaper"}}}}}},"404":{"description":"Newspaper not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/states":{"get":{"summary":"List all states + their cities","responses":{"200":{"description":"State list","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}}}}}}}}}},"/v1/countries":{"get":{"summary":"List all countries","responses":{"200":{"description":"Country list","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}}}}}}},"/v1/categories":{"get":{"summary":"List all categories","responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/v1/conferences":{"get":{"summary":"List conferences","description":"Press-conference and broadcast transcripts (e.g. the Mexican morning briefings). Returns metadata and EN/ES summaries; use /v1/conferences/{videoId} for the full transcript.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Whole-word search across the transcript (accent-insensitive), ranked by relevance. Returns the matching segments with timestamps.","example":"seguridad"},{"name":"complete","in":"query","schema":{"type":"boolean"},"description":"Filter by processing state (true/false)."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Only conferences published on/after this ISO date.","example":"2026-05-01"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Only conferences published on/before this ISO date.","example":"2026-05-22"},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"example":1}],"responses":{"200":{"description":"Paginated conference list","content":{"application/json":{"schema":{"type":"object","required":["status","totalResults","conferences"],"properties":{"status":{"type":"string","enum":["ok"]},"totalResults":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"conferences":{"type":"array","items":{"$ref":"#/components/schemas/Conference"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/conferences/{videoId}":{"get":{"summary":"Get one conference","description":"Full transcript text, structured topics, and timed segments for a single conference.","parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conference detail","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"conference":{"$ref":"#/components/schemas/ConferenceDetail"}}}}}},"404":{"description":"Conference not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/front-pages":{"get":{"summary":"List front pages","description":"Newspaper front pages with the cover image, per-article synopses, and analysis. Defaults to the most recent day; use date or from/to for history.","parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"Single day (YYYY-MM-DD). Defaults to the most recent available day.","example":"2026-05-22"},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Range start (YYYY-MM-DD). Requires `to`; max 31 days."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Range end (YYYY-MM-DD). Requires `from`; max 31 days."},{"name":"newspapers","in":"query","schema":{"type":"string"},"description":"CSV of newspaper slugs. Prefix with `-` to exclude.","example":"reforma,-el-universal"},{"name":"country","in":"query","schema":{"type":"string"},"description":"CSV of country slugs (from /v1/countries).","example":"mexico"},{"name":"state","in":"query","schema":{"type":"string"},"description":"CSV of state slugs (from /v1/states).","example":"cdmx"},{"name":"city","in":"query","schema":{"type":"string"},"description":"CSV of city slugs."},{"name":"category","in":"query","schema":{"type":"string","enum":["columns","culture-and-art","economy-and-finance","education","employment","entertainment","environment","government","health","other","politics","public-works","security","sports","tourism","transportation","urban-development"]},"description":"CSV of category slugs (English).","example":"security"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"CSV of fields to include: imageUrl, place, categories, analysis, articles. Default: all.","example":"imageUrl,place,articles"},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"example":1}],"responses":{"200":{"description":"Front page list","content":{"application/json":{"schema":{"type":"object","required":["status","totalResults","frontPages"],"properties":{"status":{"type":"string","enum":["ok"]},"date":{"type":"string","format":"date","nullable":true},"totalResults":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"frontPages":{"type":"array","items":{"$ref":"#/components/schemas/FrontPage"}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}