{"openapi":"3.1.1","info":{"title":"Briefs API and feeds","version":"1.0.0","description":"Read-only publisher headlines and previews. No full article bodies. Publisher material retains its existing rights; no additional content licence is granted."},"servers":[{"url":"https://briefs.fyi"}],"externalDocs":{"url":"https://briefs.fyi/api-and-feeds"},"paths":{"/api/news":{"get":{"operationId":"listNews","summary":"Search and paginate grouped news previews","description":"No authentication required. Prefer counts=0 when totals are unnecessary. Suggested polling interval: five minutes per distinct query. Publication, discovery and metadata-update dates are milliseconds; coverage is incomplete.","parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":150},"description":"Search headlines and previews; explicit wildcards are supported."},{"in":"query","name":"source","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat source IDs to select publishers. Omit for all; none selects no sources. IDs are listed in the first API response."},{"in":"query","name":"match","schema":{"type":"string","enum":["all","any","phrase","boolean"],"default":"all"},"description":"Whole-word matching mode."},{"in":"query","name":"hide_paywalled","schema":{"type":"string","enum":["0","1"],"default":"0"},"description":"1 excludes publisher-estimated or confirmed paywalls."},{"in":"query","name":"access","schema":{"type":"string","enum":["free","subscription","registration","metered","unknown"]},"description":"Filter saved per-article access metadata."},{"in":"query","name":"counts","schema":{"type":"string","enum":["0","1"],"default":"1"},"description":"0 omits totals when q is empty. Searches retain counts."},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Opaque nextCursor from the previous response, with the same filters."}],"responses":{"200":{"description":"A page of at most 50 grouped stories.","content":{"application/json":{"schema":{"type":"object","required":["articles","total","more","nextCursor","sources","canBroadenSearch","refreshing"],"properties":{"articles":{"type":"array","maxItems":50,"items":{"type":"object","required":["id","url","source","title","description","image","publishedAt","discoveredAt","updatedAt","access","paywall","archiveUrl","bulletin","copies"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"source":{"type":"string"},"title":{"type":"string"},"access":{"type":"string","enum":["free","subscription","registration","metered","unknown"]},"publishedAt":{"type":["integer","null"],"format":"int64","description":"Unix timestamp in milliseconds."},"paywall":{"oneOf":[{"type":"null"},{"type":"object","required":["kind","reason"],"properties":{"kind":{"type":"string","enum":["publisher","estimate"]},"reason":{"type":"string"}}}]},"archiveUrl":{"type":"string","format":"uri"},"description":{"type":"string"},"image":{"type":"string","description":"Publisher thumbnail URL, or an empty string."},"discoveredAt":{"type":"integer","format":"int64","description":"Unix timestamp in milliseconds."},"updatedAt":{"type":"integer","format":"int64","description":"Unix timestamp in milliseconds."},"discussionUrl":{"type":"string","format":"uri"},"submitted":{"type":"boolean"},"bulletin":{"type":"boolean"},"copies":{"type":"array","items":{"type":"object","required":["id","url","source","title","access","publishedAt","paywall","archiveUrl"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"source":{"type":"string"},"title":{"type":"string"},"access":{"type":"string","enum":["free","subscription","registration","metered","unknown"]},"publishedAt":{"type":["integer","null"],"format":"int64","description":"Unix timestamp in milliseconds."},"paywall":{"oneOf":[{"type":"null"},{"type":"object","required":["kind","reason"],"properties":{"kind":{"type":"string","enum":["publisher","estimate"]},"reason":{"type":"string"}}}]},"archiveUrl":{"type":"string","format":"uri"}}}}}}},"total":{"type":["integer","null"]},"more":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"canBroadenSearch":{"type":"boolean"},"refreshing":{"type":"boolean"},"sources":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"matchCount":{"type":"integer"},"hasMatches":{"type":"boolean"},"filterState":{"type":"string","enum":["available","paywall-hidden","no-matches"]}}}}}}}}},"400":{"description":"Invalid query or cursor.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"405":{"description":"Only GET and HEAD are supported."},"500":{"description":"Temporary service error."}}}},"/feed.xml":{"get":{"operationId":"readRSS","summary":"Recent previews as RSS 2.0","parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":150},"description":"Search headlines and previews; explicit wildcards are supported."},{"in":"query","name":"source","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat source IDs to select publishers. Omit for all; none selects no sources. IDs are listed in the first API response."},{"in":"query","name":"match","schema":{"type":"string","enum":["all","any","phrase","boolean"],"default":"all"},"description":"Whole-word matching mode."},{"in":"query","name":"hide_paywalled","schema":{"type":"string","enum":["0","1"],"default":"1"},"description":"1 excludes publisher-estimated or confirmed paywalls."},{"in":"query","name":"access","schema":{"type":"string","enum":["free","subscription","registration","metered","unknown"]},"description":"Filter saved per-article access metadata."},{"in":"header","name":"If-None-Match","schema":{"type":"string"}}],"responses":{"200":{"description":"Up to 50 recent grouped previews.","headers":{"ETag":{"description":"Send as If-None-Match on the next request.","schema":{"type":"string"}}},"content":{"application/rss+xml":{"schema":{"type":"string"}}}},"304":{"description":"The ETag still matches. Reuse the cached feed."},"400":{"description":"Invalid query or cursor.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"Temporary service error."}}}},"/atom.xml":{"get":{"operationId":"readAtom","summary":"Recent previews as Atom","parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":150},"description":"Search headlines and previews; explicit wildcards are supported."},{"in":"query","name":"source","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeat source IDs to select publishers. Omit for all; none selects no sources. IDs are listed in the first API response."},{"in":"query","name":"match","schema":{"type":"string","enum":["all","any","phrase","boolean"],"default":"all"},"description":"Whole-word matching mode."},{"in":"query","name":"hide_paywalled","schema":{"type":"string","enum":["0","1"],"default":"1"},"description":"1 excludes publisher-estimated or confirmed paywalls."},{"in":"query","name":"access","schema":{"type":"string","enum":["free","subscription","registration","metered","unknown"]},"description":"Filter saved per-article access metadata."},{"in":"header","name":"If-None-Match","schema":{"type":"string"}}],"responses":{"200":{"description":"Up to 50 recent grouped previews.","headers":{"ETag":{"description":"Send as If-None-Match on the next request.","schema":{"type":"string"}}},"content":{"application/atom+xml":{"schema":{"type":"string"}}}},"304":{"description":"The ETag still matches. Reuse the cached feed."},"400":{"description":"Invalid query or cursor.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"Temporary service error."}}}}}}