{ "openapi": "3.1.0", "info": { "title": "AI HOT Public API", "version": "1.1.0", "description": "Stable anonymous, read-only API for private clients and Agents. No API key is required.\n\nPicking an endpoint: show recent or today's items -> /api/v1/items. Show what is trending right now -> /api/v1/hot-topics. Show the daily digest -> /api/v1/dailies/latest. Keep a complete local copy of the selected set -> /api/v1/selected/snapshot once, then /api/v1/selected/changes forever.\n\nHow often content actually changes: new items flow in all day, while the selected set typically changes a few to a few dozen times per day, and the daily report is published once a day at 08:00 Asia/Shanghai.\n\nHow often to poll: use each response's Cache-Control s-maxage as the minimum interval — currently 60s for /api/v1/items and 300s for /api/v1/hot-topics. Anything faster returns the same shared-cache copy, so it costs you requests and buys you nothing. Always send If-None-Match: an unchanged resource answers 304 with an empty body, which is what makes frequent polling cheap for both sides. Published rate limits and burst allowances live at https://aihot.virxact.com/agent?tab=api; on 429 or 503, honour Retry-After.\n\nThere is no push channel (no SSE, webhooks or streaming), and that is deliberate: responses are served from shared caches whose TTL already bounds how fresh any client can be, so conditional polling at s-maxage gets you the same freshness without a connection to keep alive. Poll on an interval; do not hold connections open.\n\nAttribution for public products: show one discoverable ‘Data source: AI HOT’ link at product level, for example in a footer, About page, or data-sources page. Per-item attribution is not required, and private or internal use needs no UI attribution. This does not authorize pure mirrors or bulk public redistribution.", "license": { "name": "AI HOT API Terms", "url": "https://aihot.virxact.com/terms" } }, "servers": [ { "url": "https://aihot.virxact.com" } ], "externalDocs": { "description": "Machine-readable OpenAPI document", "url": "https://aihot.virxact.com/openapi-v1.json" }, "paths": { "/api/v1/items": { "get": { "operationId": "items", "summary": "List recent public AI items", "description": "Start here for feeds, widgets and 'what is new' views. Covers the last 7 days only. Send If-None-Match and you get a 304 with an empty body whenever nothing changed. Do not use this to maintain a complete local copy of the selected set: it is windowed, so anything older than 7 days silently falls out. Use /api/v1/selected/snapshot plus /api/v1/selected/changes for that.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "selected", "all" ], "default": "selected" } }, { "name": "category", "in": "query", "schema": { "type": "string", "examples": [ "ai-models", "ai-products", "industry", "paper", "tip" ], "description": "Current values: ai-models, ai-products, industry, paper, tip." } }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d" ], "default": "7d" } }, { "name": "by", "in": "query", "schema": { "type": "string", "enum": [ "timeline", "published" ], "default": "timeline" }, "description": "Which timestamp defines the window and the ordering. 'timeline' (default) matches what aihot.virxact.com shows: items back-filled more than 72h after publication keep their original publication date, everything else uses the time AI HOT received it, so slow-pushing sources still land inside a 24h window. 'published' uses the third-party publication time only, which drops those slow pushes out of short windows. Both timestamps are always returned on every item as publishedAt and discoveredAt." }, { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "description": "Leading and trailing whitespace is removed before validation; the remaining value must contain 2 to 200 Unicode code points." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque, query-bound keyset cursor for the rolling window. It carries no issue time and does not expire on a timer, but the window keeps moving: once the cursor's own anchor has dropped out of the requested 24h or 7d window it is rejected with invalid_cursor, so restart the query from the first page instead of persisting a cursor across days. Older rows may also naturally leave the window between requests. Use selected snapshot + changes for an exact mirror." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/hot-topics": { "get": { "operationId": "hotTopics", "summary": "List current multi-source hot topics", "description": "The current AI HOT Top 10, ranked by multi-source coverage and discussion heat. Each item includes a one-based rank; internal and display heat values are not returned. Recomputed continuously, but served from a 300s shared cache: that cache window is the floor on how fresh any client can be, so polling faster than s-maxage returns the same copy. Use If-None-Match. If an item includes links.story, it is a human-facing HTML URL: extract its final publicId path segment and call /api/v1/stories/{publicId} for timeline JSON. Never request links.story as an API. When absent, do not construct a story id.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotTopicsResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/stories/{publicId}": { "get": { "operationId": "storyByPublicId", "summary": "Get a story (event) with its coverage timeline and AI digest", "description": "One story = one real-world event aggregated from every covering source: a reverse-chronological coverage timeline, an AI digest that is rewritten incrementally as the event evolves (contradictions with earlier reporting are stated explicitly), and links to same-storyline and related stories. Extract ids from the final path segment of a hot-topics links.story HTML URL, or use ids from another story's storyline/related refs; never request links.story as JSON. Merged stories answer with a 308 to the surviving id. Call this endpoint only with an id actually returned by the API; a 404 means the public story layer or that story is unavailable.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "308": { "description": "Story was merged into another; follow Location to the surviving story id." }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/dailies": { "get": { "operationId": "dailies", "summary": "List daily-report archive entries", "description": "Date index of past daily reports, newest first. Reports are published once a day at 08:00 Asia/Shanghai, so checking this more than a few times a day is wasted work.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailiesResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/dailies/latest": { "get": { "operationId": "latestDaily", "summary": "Get the latest daily report", "description": "The most recent daily report, published once a day at 08:00 Asia/Shanghai. A client that only wants the daily digest should wake up shortly after 08:00 rather than poll around the clock.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/dailies/{date}": { "get": { "operationId": "dailyByDate", "summary": "Get a daily report by Shanghai calendar date", "description": "A single past daily report by Asia/Shanghai calendar date (YYYY-MM-DD). Past reports are immutable, so a client may cache them indefinitely and never re-fetch a date it already has.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyResponse" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/selected/snapshot": { "get": { "operationId": "selectedSnapshot", "summary": "Fetch the current selected-item snapshot, one page at a time", "description": "One-time bootstrap for clients that keep a complete local copy of the selected set. Not a browsing endpoint and not something to poll: page through it once with limit (default 500, max 1000) until hasMore is false, keep the cursor from the FIRST page, then stay current with /api/v1/selected/changes. The full set runs to several thousand items and only grows; fields=minimal keeps the bootstrap small. A widget that just shows today's picks does not need this at all — use /api/v1/items.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "fields", "in": "query", "schema": { "type": "string", "enum": [ "default", "minimal" ], "default": "default" }, "description": "'minimal' drops summary and the original-article link, cutting the payload roughly 4x. Prefer it when you only need to know which items are currently selected. On continuation pages the value is locked by the page cursor, so a mirror can never end up half default and half minimal." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "page", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from the previous response's nextPage. Keep requesting pages while hasMore is true; only after the last page should you use cursor against /api/v1/selected/changes. The sync cursor is identical on every page and always refers to the watermark taken on the first page, so items changed mid-pagination are reconciled by the first changes call." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedSnapshot" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/selected/changes": { "get": { "operationId": "selectedChanges", "summary": "Fetch atomic selected-item changes", "description": "Adds, edits and removals since your cursor, so a local copy stays correct without re-downloading anything. Apply a page, then save the returned cursor — never the other way round. The cursor is a ledger watermark, not a session: it does not expire on a timer, so a client may go offline for days and resume exactly where it stopped. On 409 snapshot_required, re-bootstrap from /api/v1/selected/snapshot; that response is the only signal that resuming is no longer safe.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "cursor", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedChanges" } } } }, "304": { "description": "Not Modified", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Machine-readable problem response.", "headers": { "X-Request-Id": { "description": "Support correlation identifier for this failed request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "parameters": { "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "Previously received ETag for this exact URL. A match returns 304 without a response body.", "schema": { "type": "string" } } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "requestId" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } } }, "Attribution": { "type": "object", "description": "Machine-readable AI HOT provenance. Public products may attribute once at a discoverable product-level location; per-item labels are not required.", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "Item": { "type": "object", "required": [ "id", "title", "originalTitle", "summary", "source", "links", "publishedAt", "discoveredAt", "category", "score", "selected" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "originalTitle": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" } } }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "discoveredAt": { "type": "string", "format": "date-time" }, "category": { "type": [ "string", "null" ], "examples": [ "ai-models", "ai-products", "industry", "paper", "tip" ], "description": "Current values: ai-models, ai-products, industry, paper, tip. Clients must tolerate future string values." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "selected": { "type": "boolean" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "ItemMinimal": { "type": "object", "required": [ "id", "title", "source", "links", "publishedAt", "discoveredAt", "category", "score", "selected" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "discoveredAt": { "type": "string", "format": "date-time" }, "category": { "type": [ "string", "null" ], "examples": [ "ai-models", "ai-products", "industry", "paper", "tip" ], "description": "Current values: ai-models, ai-products, industry, paper, tip. Clients must tolerate future string values." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "selected": { "type": "boolean" } } }, "Page": { "type": "object", "required": [ "count", "hasMore", "nextCursor" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Number of records in this page." }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque; only reuse with the same query." } } }, "ItemsResponse": { "type": "object", "required": [ "schemaVersion", "query", "items", "page" ], "properties": { "schemaVersion": { "const": 1 }, "query": { "type": "object", "required": [ "mode", "category", "window", "q", "by", "ordering" ], "properties": { "mode": { "type": "string", "enum": [ "selected", "all" ] }, "category": { "type": [ "string", "null" ], "examples": [ "ai-models", "ai-products", "industry", "paper", "tip" ], "description": "Current values: ai-models, ai-products, industry, paper, tip. Clients must tolerate future string values." }, "window": { "type": "string", "enum": [ "24h", "7d" ] }, "q": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 200 }, "by": { "type": "string", "enum": [ "timeline", "published" ] }, "ordering": { "type": "string", "enum": [ "timelineDesc", "publishedAtDesc" ] } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "HotTopic": { "type": "object", "required": [ "rank", "id", "title", "source", "links", "sourceCount", "signalCount", "sourceNames", "latestAt" ], "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 10, "description": "One-based position in the current AI HOT Top 10 response." }, "id": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" }, "story": { "type": "string", "format": "uri", "description": "Optional human-facing HTML URL. Extract its final publicId path segment and call /api/v1/stories/{publicId} for JSON; never request this URL as an API. Do not construct story ids when absent." } } }, "sourceCount": { "type": "integer", "minimum": 0 }, "signalCount": { "type": "integer", "minimum": 0 }, "sourceNames": { "type": "array", "items": { "type": "string" } }, "latestAt": { "type": "string", "format": "date-time" } } }, "HotTopicsResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HotTopic" } } } }, "StoryReport": { "type": "object", "required": [ "id", "title", "summary", "source", "publishedAt", "links" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "source": { "type": "object", "required": [ "name", "firstParty" ], "properties": { "name": { "type": "string" }, "firstParty": { "type": "boolean" } } }, "publishedAt": { "type": "string", "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" } } } } }, "StoryNeighbor": { "type": "object", "required": [ "publicId", "title", "relation", "links" ], "properties": { "publicId": { "type": "string" }, "title": { "type": "string" }, "relation": { "type": "string" }, "links": { "type": "object", "required": [ "aihot", "api" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } } } } }, "Story": { "type": "object", "required": [ "publicId", "title", "status", "sourceCount", "reportCount", "firstReportAt", "latestAt", "latest", "digest", "digestUpdatedAt", "links", "reports", "storyline", "related" ], "properties": { "publicId": { "type": "string" }, "title": { "type": "string" }, "status": { "enum": [ "active", "settled" ] }, "sourceCount": { "type": "integer", "minimum": 0 }, "reportCount": { "type": "integer", "minimum": 0 }, "firstReportAt": { "type": "string", "format": "date-time" }, "latestAt": { "type": "string", "format": "date-time" }, "latest": { "type": "string" }, "digest": { "type": [ "string", "null" ] }, "digestUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/StoryReport" } }, "storyline": { "type": "array", "items": { "$ref": "#/components/schemas/StoryNeighbor" } }, "related": { "type": "array", "items": { "$ref": "#/components/schemas/StoryNeighbor" } } } }, "StoryResponse": { "type": "object", "required": [ "schemaVersion", "story" ], "properties": { "schemaVersion": { "const": 1 }, "story": { "$ref": "#/components/schemas/Story" } } }, "DailiesResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DailyEntry" } } } }, "DailyEntry": { "type": "object", "required": [ "date", "generatedAt", "leadTitle", "leadParagraph", "links" ], "properties": { "date": { "type": "string", "format": "date" }, "generatedAt": { "type": "string", "format": "date-time" }, "leadTitle": { "type": [ "string", "null" ] }, "leadParagraph": { "type": [ "string", "null" ] }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "DailyContentLinks": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": [ "string", "null" ], "format": "uri" }, "original": { "type": "string", "format": "uri" } } }, "DailyReport": { "type": "object", "required": [ "date", "generatedAt", "windowStart", "windowEnd", "links", "lead", "sections", "flashes" ], "properties": { "date": { "type": "string", "format": "date" }, "generatedAt": { "type": "string", "format": "date-time" }, "windowStart": { "type": "string", "format": "date-time" }, "windowEnd": { "type": "string", "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "lead": { "anyOf": [ { "type": "object", "required": [ "title", "leadParagraph" ], "properties": { "title": { "type": "string" }, "leadParagraph": { "type": "string" } } }, { "type": "null" } ] }, "sections": { "type": "array", "items": { "type": "object", "required": [ "label", "items" ], "properties": { "label": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "title", "summary", "source", "links" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "$ref": "#/components/schemas/DailyContentLinks" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } } }, "flashes": { "type": "array", "items": { "type": "object", "required": [ "title", "source", "links", "publishedAt" ], "properties": { "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "$ref": "#/components/schemas/DailyContentLinks" }, "publishedAt": { "type": "string", "format": "date-time" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "DailyResponse": { "type": "object", "required": [ "schemaVersion", "report" ], "properties": { "schemaVersion": { "const": 1 }, "report": { "$ref": "#/components/schemas/DailyReport" } } }, "SelectedSnapshot": { "type": "object", "required": [ "schemaVersion", "asOf", "fields", "cursor", "count", "hasMore", "nextPage", "items" ], "properties": { "schemaVersion": { "const": 1 }, "asOf": { "type": "string", "format": "date-time" }, "fields": { "type": "string", "enum": [ "default", "minimal" ] }, "cursor": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "nextPage": { "type": [ "string", "null" ] }, "items": { "type": "array" } }, "oneOf": [ { "properties": { "fields": { "const": "default" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } }, { "properties": { "fields": { "const": "minimal" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemMinimal" } } } } ] }, "SelectedRemove": { "type": "object", "required": [ "op", "changedAt", "id" ], "properties": { "op": { "const": "remove" }, "changedAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" } } }, "SelectedUpsert": { "type": "object", "required": [ "op", "changedAt", "item" ], "properties": { "op": { "const": "upsert" }, "changedAt": { "type": "string", "format": "date-time" }, "item": { "$ref": "#/components/schemas/Item" } } }, "SelectedUpsertMinimal": { "type": "object", "required": [ "op", "changedAt", "item" ], "properties": { "op": { "const": "upsert" }, "changedAt": { "type": "string", "format": "date-time" }, "item": { "$ref": "#/components/schemas/ItemMinimal" } } }, "SelectedChanges": { "type": "object", "required": [ "schemaVersion", "fields", "cursor", "count", "hasMore", "changes" ], "properties": { "schemaVersion": { "const": 1 }, "fields": { "type": "string", "enum": [ "default", "minimal" ] }, "cursor": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "changes": { "type": "array" } }, "oneOf": [ { "properties": { "fields": { "const": "default" }, "changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SelectedUpsert" }, { "$ref": "#/components/schemas/SelectedRemove" } ] } } } }, { "properties": { "fields": { "const": "minimal" }, "changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SelectedUpsertMinimal" }, { "$ref": "#/components/schemas/SelectedRemove" } ] } } } } ] } } } }