{ "components": { "schemas": { "AlertKeywordV1": { "properties": { "case_sensitive": { "default": false, "title": "Case Sensitive", "type": "boolean" }, "keyword": { "description": "Whole word or phrase; `$AAPL` -> `AAPL`.", "minLength": 1, "title": "Keyword", "type": "string" } }, "required": [ "keyword" ], "title": "AlertKeywordV1", "type": "object" }, "AlertRuleIn": { "examples": [ { "channels": [ "phone" ], "enabled": true, "exclude": [], "include": [ { "case_sensitive": true, "keyword": "AAPL" } ], "match": "any", "match_in": [ "title", "summary" ], "max_per_hour": 10, "name": "Big tech tickers", "notify_on_update": false, "priority": "high", "quiet_hours": { "end": "07:00", "start": "22:00" }, "source_ids": [] } ], "properties": { "channels": { "default": [], "description": "Channel keys of the profile.", "items": { "type": "string" }, "title": "Channels", "type": "array" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "exclude": { "default": [], "items": { "$ref": "#/components/schemas/AlertKeywordV1" }, "title": "Exclude", "type": "array" }, "include": { "items": { "$ref": "#/components/schemas/AlertKeywordV1" }, "minItems": 1, "title": "Include", "type": "array" }, "match": { "default": "any", "enum": [ "any", "all" ], "title": "Match", "type": "string" }, "match_in": { "default": [ "title", "summary" ], "items": { "enum": [ "title", "summary", "text" ], "type": "string" }, "minItems": 1, "title": "Match In", "type": "array" }, "max_per_hour": { "default": 10, "maximum": 1000.0, "minimum": 1.0, "title": "Max Per Hour", "type": "integer" }, "name": { "maxLength": 100, "minLength": 1, "title": "Name", "type": "string" }, "notify_on_update": { "default": false, "title": "Notify On Update", "type": "boolean" }, "priority": { "default": "default", "enum": [ "low", "default", "high" ], "title": "Priority", "type": "string" }, "quiet_hours": { "anyOf": [ { "$ref": "#/components/schemas/QuietHoursV1" }, { "type": "null" } ] }, "source_ids": { "default": [], "description": "Empty: all the profile's sources.", "items": { "type": "string" }, "title": "Source Ids", "type": "array" } }, "required": [ "name", "include" ], "title": "AlertRuleIn", "type": "object" }, "AlertRuleV1": { "examples": [ { "channels": [ "phone" ], "enabled": true, "exclude": [], "id": 3, "include": [ { "case_sensitive": true, "keyword": "AAPL" } ], "match": "any", "match_in": [ "title", "summary" ], "max_per_hour": 10, "name": "Big tech tickers", "notify_on_update": false, "priority": "high", "quiet_hours": { "end": "07:00", "start": "22:00" }, "source_ids": [] } ], "properties": { "channels": { "default": [], "description": "Channel keys of the profile.", "items": { "type": "string" }, "title": "Channels", "type": "array" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "exclude": { "default": [], "items": { "$ref": "#/components/schemas/AlertKeywordV1" }, "title": "Exclude", "type": "array" }, "id": { "title": "Id", "type": "integer" }, "include": { "items": { "$ref": "#/components/schemas/AlertKeywordV1" }, "minItems": 1, "title": "Include", "type": "array" }, "match": { "default": "any", "enum": [ "any", "all" ], "title": "Match", "type": "string" }, "match_in": { "default": [ "title", "summary" ], "items": { "enum": [ "title", "summary", "text" ], "type": "string" }, "minItems": 1, "title": "Match In", "type": "array" }, "max_per_hour": { "default": 10, "maximum": 1000.0, "minimum": 1.0, "title": "Max Per Hour", "type": "integer" }, "name": { "maxLength": 100, "minLength": 1, "title": "Name", "type": "string" }, "notify_on_update": { "default": false, "title": "Notify On Update", "type": "boolean" }, "priority": { "default": "default", "enum": [ "low", "default", "high" ], "title": "Priority", "type": "string" }, "quiet_hours": { "anyOf": [ { "$ref": "#/components/schemas/QuietHoursV1" }, { "type": "null" } ] }, "source_ids": { "default": [], "description": "Empty: all the profile's sources.", "items": { "type": "string" }, "title": "Source Ids", "type": "array" } }, "required": [ "name", "include", "id" ], "title": "AlertRuleV1", "type": "object" }, "AskV1": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Continue this conversation; omit to start one.", "title": "Conversation Id" }, "question": { "maxLength": 500, "minLength": 1, "title": "Question", "type": "string" } }, "required": [ "question" ], "title": "AskV1", "type": "object" }, "BriefOut": { "properties": { "basis": { "enum": [ "full_text", "feed_summary", "mixed" ], "title": "Basis", "type": "string" }, "bullets": { "description": "Three supporting points (empty for a fallback brief).", "items": { "$ref": "#/components/schemas/CitedTextOut" }, "title": "Bullets", "type": "array" }, "generated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Generated At" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`Summary unavailable: ` on a snippet fallback.", "title": "Label" }, "lead": { "description": "One sentence: what happened.", "title": "Lead", "type": "string" }, "lead_citations": { "items": { "$ref": "#/components/schemas/CitationOut" }, "title": "Lead Citations", "type": "array" }, "model": { "title": "Model", "type": "string" }, "sources": { "description": "Numbered sources, [1] first.", "items": { "$ref": "#/components/schemas/CitationOut" }, "title": "Sources", "type": "array" }, "status": { "description": "`fallback`: the brief failed validation; `lead` is a Phase 4 style summary (`style: summary`) or the feed snippet (`style: snippet`).", "enum": [ "ok", "fallback" ], "title": "Status", "type": "string" }, "style": { "enum": [ "brief", "summary", "snippet" ], "title": "Style", "type": "string" } }, "required": [ "lead", "lead_citations", "bullets", "status", "style", "basis", "model", "generated_at", "sources" ], "title": "BriefOut", "type": "object" }, "CatalogEntryV1": { "examples": [ { "aggregator": false, "category": "Regulators", "first_party": true, "id": "federal-reserve-press-releases", "name": "Federal Reserve press releases", "tags": [ "fed", "rates" ], "type": "rss", "url": "https://www.federalreserve.gov/feeds/press_all.xml" } ], "properties": { "aggregator": { "title": "Aggregator", "type": "boolean" }, "category": { "title": "Category", "type": "string" }, "first_party": { "title": "First Party", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "type": { "$ref": "#/components/schemas/SourceType" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "category", "name", "url", "type", "tags", "first_party", "aggregator", "note" ], "title": "CatalogEntryV1", "type": "object" }, "ChatCitationV1": { "properties": { "article_id": { "title": "Article Id", "type": "integer" }, "headline": { "title": "Headline", "type": "string" }, "index": { "title": "Index", "type": "integer" }, "publisher": { "title": "Publisher", "type": "string" }, "source": { "title": "Source", "type": "string" }, "url": { "title": "Url", "type": "string" }, "via": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Via" } }, "required": [ "index", "article_id", "source", "publisher", "headline", "url" ], "title": "ChatCitationV1", "type": "object" }, "ChatStatusV1": { "examples": [ { "message": "", "model": "qwen3.5-9b", "profile": "personal-reader", "prompt_version": "chat-v1", "state": "ok" } ], "properties": { "message": { "title": "Message", "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "profile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile" }, "prompt_version": { "default": "chat-v1", "title": "Prompt Version", "type": "string" }, "state": { "enum": [ "ok", "unset", "unreachable", "unauthorized" ], "title": "State", "type": "string" } }, "required": [ "profile", "state", "message" ], "title": "ChatStatusV1", "type": "object" }, "CitationOut": { "properties": { "headline": { "title": "Headline", "type": "string" }, "index": { "description": "The [n] marker used in the brief/report.", "title": "Index", "type": "integer" }, "origin": { "default": "feed", "description": "`feed`: a configured source; `enrichment`: found by web search for this story.", "enum": [ "feed", "enrichment" ], "title": "Origin", "type": "string" }, "publisher": { "default": "", "description": "The primary label: the article URL's domain (e.g. `ai.meta.com`).", "title": "Publisher", "type": "string" }, "source": { "title": "Source", "type": "string" }, "url": { "description": "The cited article's own permalink (never the canonical URL).", "title": "Url", "type": "string" }, "via": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The aggregator feed it came through (`Hacker News`), shown as \"via ...\"; null for a publisher's own feed.", "title": "Via" } }, "required": [ "index", "source", "headline", "url" ], "title": "CitationOut", "type": "object" }, "CitedTextOut": { "properties": { "citations": { "description": "The sources this text cites.", "items": { "$ref": "#/components/schemas/CitationOut" }, "title": "Citations", "type": "array" }, "provenance": { "default": "feed", "description": "`web`: every citation is an enrichment source; `mixed`: both kinds; `feed`: feed sources only or uncited.", "enum": [ "feed", "mixed", "web" ], "title": "Provenance", "type": "string" }, "text": { "title": "Text", "type": "string" } }, "required": [ "text", "citations" ], "title": "CitedTextOut", "type": "object" }, "ContextLinkV1": { "description": "A background/context link found by web search — related, never coverage of the\nsame event; not a source of the story, never summarized or alerted on.", "properties": { "angle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The search angle that surfaced it (`history`, `opposing view`...).", "title": "Angle" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the page's verified publication date.", "title": "Date" }, "domain": { "description": "The page's registrable domain (`wikipedia.org`).", "title": "Domain", "type": "string" }, "fact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the verified <=30-word grounded fact.", "title": "Fact" }, "kind": { "default": "article", "description": "`opinion` when the page is an opinion/column piece (at most `context.max_opinion` per story); `fact_check` when the counter-narrative angle found a fact-check page; `article` otherwise.", "enum": [ "article", "opinion", "fact_check" ], "title": "Kind", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What it adds (the LLM judge's <=25-word note).", "title": "Note" }, "origin": { "anyOf": [ { "enum": [ "archive", "web" ], "type": "string" }, { "type": "null" } ], "description": "Planner mode: `archive` when the page came from an older-window retrieval query, `web` otherwise.", "title": "Origin" }, "outlet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the publisher alias (== `domain`).", "title": "Outlet" }, "quote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the verbatim evidence quote (<=25 words) from the page.", "title": "Quote" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the named entity the task covers.", "title": "Subject" }, "title": { "title": "Title", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Planner mode: the retrieval-catalog task the item serves (history | quotes | financials | related_developments | background); null for angles-mode links.", "title": "Type" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "title", "domain" ], "title": "ContextLinkV1", "type": "object" }, "ConversationV1": { "examples": [ { "created_at": "2026-10-12T08:30:00Z", "id": "0b6c3f9e-8a51-4c1e-9f0e-2d7a1b5c4e10", "last_active_at": "2026-10-12T08:31:00Z", "messages": [ { "content": "When does it ship?", "created_at": "2026-10-12T08:30:00Z", "id": 1, "role": "user", "status": "complete" }, { "citations": [ { "article_id": 7, "headline": "Meta unveils ...", "index": 1, "publisher": "ai.meta.com", "source": "Hacker News", "url": "https://ai.meta.com/blog/...", "via": "Hacker News" } ], "content": "The company says it ships in May [1].", "created_at": "2026-10-12T08:30:05Z", "id": 2, "role": "assistant", "status": "complete", "verification": { "cited": [ 1 ], "refusal": false, "verified": true } } ], "story_id": 42 } ], "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_active_at": { "format": "date-time", "title": "Last Active At", "type": "string" }, "messages": { "items": { "$ref": "#/components/schemas/MessageV1" }, "title": "Messages", "type": "array" }, "story_id": { "title": "Story Id", "type": "integer" } }, "required": [ "id", "story_id", "created_at", "last_active_at", "messages" ], "title": "ConversationV1", "type": "object" }, "DiscoverIn": { "properties": { "url": { "description": "A site or feed URL.", "examples": [ "https://www.theverge.com" ], "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "DiscoverIn", "type": "object" }, "EnrichStatusV1": { "examples": [ { "last_pass_at": "2026-10-22T11:29:40Z", "last_stage_event_at": "2026-10-22T11:30:05Z", "last_sweep_at": "2026-10-22T11:30:00Z", "last_watchdog_at": "2026-10-22T11:29:00Z", "pending": 4, "provider": "tinyfish", "provider_requests_since_start": 37, "retries_due": 0, "sweep_recent": true, "thread_alive": true, "tinyfish_requests_since_start": 37, "watchdog_restarts": 0 } ], "properties": { "last_cluster_duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Cluster Duration Ms" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The worker's last unexpected error.", "title": "Last Error" }, "last_error_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Error At" }, "last_images_duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Images Duration Ms" }, "last_lock_error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Last 'database is locked' error (``table`` and ``at``).", "title": "Last Lock Error" }, "last_pass_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the worker last emptied the pending queue (this process).", "title": "Last Pass At" }, "last_report_duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Report Duration Ms" }, "last_stage_event_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Start of the newest `enrich` stage event (telemetry).", "title": "Last Stage Event At" }, "last_sweep_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Last run of the scheduled job.", "title": "Last Sweep At" }, "last_watchdog_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Watchdog At" }, "lock_errors_since_start": { "default": 0, "description": "SQLite 'database is locked' errors since process start.", "title": "Lock Errors Since Start", "type": "integer" }, "lock_retries_since_start": { "default": 0, "description": "Writes retried by ``db.retry_locked`` since process start.", "title": "Lock Retries Since Start", "type": "integer" }, "longest_write_txn_seconds": { "default": 0.0, "description": "Longest write transaction observed since process start.", "title": "Longest Write Txn Seconds", "type": "number" }, "pending": { "description": "Stories admitted and waiting for a search.", "title": "Pending", "type": "integer" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first configured search provider.", "title": "Provider" }, "provider_requests_since_start": { "title": "Provider Requests Since Start", "type": "integer" }, "retries_due": { "description": "Stories whose retry time has come.", "title": "Retries Due", "type": "integer" }, "sweep_recent": { "description": "The scheduled job ran within three of its intervals (`DISCOVER_ENRICH_INTERVAL_SECONDS`).", "title": "Sweep Recent", "type": "boolean" }, "telemetry_dropped_rows": { "default": 0, "description": "Telemetry rows dropped because the write queue ran full.", "title": "Telemetry Dropped Rows", "type": "integer" }, "telemetry_queued": { "default": 0, "description": "Telemetry rows queued for write.", "title": "Telemetry Queued", "type": "integer" }, "thread_alive": { "description": "The enrichment worker thread is running now.", "title": "Thread Alive", "type": "boolean" }, "tinyfish_requests_since_start": { "title": "Tinyfish Requests Since Start", "type": "integer" }, "watchdog_restarts": { "description": "Worker restarts by the watchdog.", "title": "Watchdog Restarts", "type": "integer" } }, "required": [ "thread_alive", "last_error", "last_error_at", "last_stage_event_at", "last_pass_at", "pending", "retries_due", "provider", "provider_requests_since_start", "tinyfish_requests_since_start", "last_sweep_at", "sweep_recent", "last_watchdog_at", "watchdog_restarts" ], "title": "EnrichStatusV1", "type": "object" }, "FeedCandidate": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "type": { "$ref": "#/components/schemas/SourceType", "default": "rss" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "FeedCandidate", "type": "object" }, "FeedV1": { "examples": [ { "include": "card", "items": [ { "brief": { "basis": "full_text", "bullets": [ { "citations": [], "text": "It ships next year." } ], "generated_at": "2026-10-12T08:30:00Z", "lead": "A chipmaker unveiled an accelerator aimed at AI agents.", "lead_citations": [ { "headline": "...", "index": 1, "source": "The Verge", "url": "..." } ], "model": "qwen3.5-9b", "sources": [], "status": "ok", "style": "brief" }, "first_seen_at": "2026-10-12T08:30:00Z", "id": 42, "last_updated_at": "2026-10-12T08:30:00Z", "published_at": "2026-10-12T08:30:00Z", "snippet": "The company said...", "source_count": 2, "source_names": [ "The Verge", "Ars Technica" ], "title": "Chipmaker unveils agent-ready accelerator", "updated_at": "2026-10-12T08:30:00Z", "url": "https://news.example/story/42", "version": 3 } ], "next_cursor": "MjAyNi0xMC0xMlQwODozMDowMCswMDowMHw0Mg", "profile": "personal-reader" } ], "properties": { "include": { "enum": [ "card", "full" ], "title": "Include", "type": "string" }, "items": { "description": "Published stories, newest update first.", "items": { "$ref": "#/components/schemas/StoryCardV1" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page.", "title": "Next Cursor" }, "profile": { "title": "Profile", "type": "string" }, "topic": { "anyOf": [ { "$ref": "#/components/schemas/TopicV1" }, { "type": "null" } ] } }, "required": [ "profile", "topic", "include", "items", "next_cursor" ], "title": "FeedV1", "type": "object" }, "FollowupsV1": { "examples": [ { "generated_at": "2026-10-12T08:30:00Z", "model": "qwen3.5-9b", "questions": [ "When will the chip ship?", "Who are its first customers?", "How does it compare with rivals?" ], "state": "ready", "story_id": 42 } ], "properties": { "generated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Generated At" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "questions": { "items": { "type": "string" }, "title": "Questions", "type": "array" }, "state": { "description": "`pending`: not generated yet (they appear after the report); `unavailable`: chat is off or generation failed.", "enum": [ "ready", "pending", "unavailable" ], "title": "State", "type": "string" }, "story_id": { "title": "Story Id", "type": "integer" } }, "required": [ "story_id", "state", "questions" ], "title": "FollowupsV1", "type": "object" }, "FunnelV1": { "examples": [ { "failure_reasons": { "enrich": [ [ "timeout", 2 ] ] }, "hours": 168.0, "retries_per_story": { "1": 6, "2": 2 }, "since": "2026-10-12T08:30:00Z", "steps": [ { "count": 60, "name": "articles ingested" }, { "count": 9, "name": "stories formed", "rate": 0.15 } ] } ], "properties": { "failure_reasons": { "additionalProperties": true, "default": {}, "title": "Failure Reasons", "type": "object" }, "hours": { "title": "Hours", "type": "number" }, "retries_per_story": { "additionalProperties": true, "default": {}, "title": "Retries Per Story", "type": "object" }, "since": { "title": "Since", "type": "string" }, "steps": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Steps", "type": "array" } }, "required": [ "since", "hours" ], "title": "FunnelV1", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "HealthV1": { "examples": [ { "database": "ok", "status": "ok", "version": "0.1.0" } ], "properties": { "database": { "enum": [ "ok", "error" ], "title": "Database", "type": "string" }, "status": { "enum": [ "ok", "degraded" ], "title": "Status", "type": "string" }, "version": { "title": "Version", "type": "string" } }, "required": [ "status", "database", "version" ], "title": "HealthV1", "type": "object" }, "ImageOut": { "description": "The story's chosen card image (validated; see ``source``).", "properties": { "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "proxy_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "This app's cached, resized WebP copy (`/img/{key}`).", "title": "Proxy Url" }, "source": { "description": "feed/page: the representative article's feed or page image; member: another member's; logo/none: no image (logo: a publisher icon is available).", "enum": [ "feed", "page", "member", "logo", "none" ], "title": "Source", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original image URL (null: no usable image).", "title": "Url" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" } }, "required": [ "url", "source" ], "title": "ImageOut", "type": "object" }, "LlmStatsV1": { "examples": [ { "busy_ms": 40000, "calls": 12, "categories": { "summarization": 10 }, "completion_tokens": 1200, "config_hashes": [ "0a1b2c3d4e5f" ], "failed": 0, "hours": 24.0, "invalid": 1, "prompt_tokens": 9000, "purposes": [ { "calls": 10, "category": "summarization", "completion_tokens": 1200, "errors": 0, "invalid": 1, "latency_ms": 40000, "median_ms": 4000, "p95_ms": 8100, "prompt_tokens": 9000, "purpose": "brief", "queue_wait_ms": 300, "tps": 30.0 } ], "queue_wait_ms": 300, "since": "2026-10-12T08:30:00Z", "slowest": [], "utilization": 0.0004, "versions": [ "abc1234" ] } ], "properties": { "busy_ms": { "default": 0, "title": "Busy Ms", "type": "integer" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "categories": { "additionalProperties": true, "default": {}, "title": "Categories", "type": "object" }, "completion_tokens": { "default": 0, "title": "Completion Tokens", "type": "integer" }, "config_hashes": { "default": [], "items": { "type": "string" }, "title": "Config Hashes", "type": "array" }, "failed": { "default": 0, "title": "Failed", "type": "integer" }, "hours": { "title": "Hours", "type": "number" }, "invalid": { "default": 0, "title": "Invalid", "type": "integer" }, "prompt_tokens": { "default": 0, "title": "Prompt Tokens", "type": "integer" }, "purposes": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Purposes", "type": "array" }, "queue_wait_ms": { "default": 0, "title": "Queue Wait Ms", "type": "integer" }, "since": { "title": "Since", "type": "string" }, "slowest": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Slowest", "type": "array" }, "utilization": { "default": 0.0, "title": "Utilization", "type": "number" }, "versions": { "default": [], "items": { "type": "string" }, "title": "Versions", "type": "array" } }, "required": [ "since", "hours" ], "title": "LlmStatsV1", "type": "object" }, "MessageV1": { "properties": { "citations": { "default": [], "items": { "$ref": "#/components/schemas/ChatCitationV1" }, "title": "Citations", "type": "array" }, "content": { "title": "Content", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "id": { "title": "Id", "type": "integer" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "model": { "default": "", "title": "Model", "type": "string" }, "prompt_version": { "default": "", "title": "Prompt Version", "type": "string" }, "role": { "enum": [ "user", "assistant" ], "title": "Role", "type": "string" }, "status": { "enum": [ "complete", "streaming", "incomplete", "error" ], "title": "Status", "type": "string" }, "time_to_first_token_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Time To First Token Ms" }, "tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens" }, "verification": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "`{verified, refusal, cited, checks}` (answers only).", "title": "Verification" } }, "required": [ "id", "role", "content", "status", "created_at" ], "title": "MessageV1", "type": "object" }, "NotificationV1": { "examples": [ { "article_id": 5120, "attempts": 1, "channel": "phone", "created_at": "2026-10-12T08:30:00Z", "id": 41, "kind": "alert", "matched": [ "AAPL" ], "rule": "Big tech tickers", "rule_id": 3, "sent_at": "2026-10-12T08:30:00Z", "status": "sent", "story_id": 1201, "title": "Apple shares jump after earnings beat", "url": "https://www.cnbc.com/2026/10/12/apple-earnings.html" } ], "properties": { "article_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Article Id" }, "attempts": { "title": "Attempts", "type": "integer" }, "channel": { "title": "Channel", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "hold_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hold Reason" }, "id": { "title": "Id", "type": "integer" }, "kind": { "enum": [ "alert", "update", "digest", "test" ], "title": "Kind", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "matched": { "default": [], "items": { "type": "string" }, "title": "Matched", "type": "array" }, "rule": { "title": "Rule", "type": "string" }, "rule_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rule Id" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sent At" }, "status": { "enum": [ "queued", "sent", "failed", "held", "digested" ], "title": "Status", "type": "string" }, "story_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The story lineage the alert belongs to.", "title": "Story Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Story page if published, else the article.", "title": "Url" } }, "required": [ "id", "rule_id", "rule", "kind", "status", "channel", "story_id", "article_id", "title", "url", "attempts", "last_error", "created_at", "sent_at" ], "title": "NotificationV1", "type": "object" }, "OpmlImportV1": { "properties": { "added": { "description": "New source ids.", "items": { "type": "string" }, "title": "Added", "type": "array" }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "shared": { "description": "Existing sources now also in this profile.", "items": { "type": "string" }, "title": "Shared", "type": "array" }, "skipped": { "description": "Already in the profile.", "items": { "type": "string" }, "title": "Skipped", "type": "array" } }, "title": "OpmlImportV1", "type": "object" }, "PreviewMatchV1": { "properties": { "article_id": { "title": "Article Id", "type": "integer" }, "fired": { "description": "This article already fired the rule.", "title": "Fired", "type": "boolean" }, "matched": { "items": { "type": "string" }, "title": "Matched", "type": "array" }, "published_at": { "format": "date-time", "title": "Published At", "type": "string" }, "source": { "title": "Source", "type": "string" }, "story_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Story Id" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "article_id", "story_id", "title", "url", "source", "published_at", "matched", "fired" ], "title": "PreviewMatchV1", "type": "object" }, "PreviewV1": { "examples": [ { "days": 7, "matches": [ { "article_id": 5120, "fired": false, "matched": [ "AAPL" ], "published_at": "2026-10-12T08:30:00Z", "source": "CNBC Markets", "story_id": 1201, "title": "Apple shares jump after earnings beat", "url": "https://www.cnbc.com/2026/10/12/apple-earnings.html" } ], "rule_id": 3, "sent": false } ], "properties": { "days": { "title": "Days", "type": "integer" }, "matches": { "items": { "$ref": "#/components/schemas/PreviewMatchV1" }, "title": "Matches", "type": "array" }, "rule_id": { "title": "Rule Id", "type": "integer" }, "sent": { "default": false, "description": "Always false: previews never notify.", "title": "Sent", "type": "boolean" } }, "required": [ "rule_id", "days", "matches" ], "title": "PreviewV1", "type": "object" }, "ProfileV1": { "examples": [ { "description": "Tech and science news", "name": "Personal reader", "slug": "personal-reader", "sources": [ { "enabled": true, "id": "the-verge", "name": "The Verge", "type": "rss", "url": "https://www.theverge.com/rss/index.xml" } ], "topics": [] } ], "properties": { "description": { "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/SourceV1" }, "title": "Sources", "type": "array" }, "topics": { "items": { "$ref": "#/components/schemas/TopicV1" }, "title": "Topics", "type": "array" } }, "required": [ "slug", "name", "description", "sources", "topics" ], "title": "ProfileV1", "type": "object" }, "QuietHoursV1": { "properties": { "end": { "examples": [ "07:00" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "title": "End", "type": "string" }, "start": { "examples": [ "22:00" ], "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "title": "Start", "type": "string" } }, "required": [ "start", "end" ], "title": "QuietHoursV1", "type": "object" }, "ReportOut": { "properties": { "details": { "default": [], "description": "Per-member text status and words.", "items": { "type": "string" }, "title": "Details", "type": "array" }, "generated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Generated At" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "model": { "title": "Model", "type": "string" }, "paragraphs": { "description": "4-6 paragraphs; empty unless ready.", "items": { "$ref": "#/components/schemas/CitedTextOut" }, "title": "Paragraphs", "type": "array" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "sources": { "description": "Numbered sources, [1] first; [1]..[n] match the brief's.", "items": { "$ref": "#/components/schemas/CitationOut" }, "title": "Sources", "type": "array" }, "state": { "description": "`pending`: published before its report (see `label`); `failed`: generation or validation failed; `skipped`: not enough source text (see `details`) the brief failed for good (`brief_failed`) or reports are off.", "enum": [ "ready", "pending", "skipped", "failed" ], "title": "State", "type": "string" }, "status": { "description": "Deprecated name of `state` (`ok` = `ready`).", "enum": [ "ok", "pending", "failed", "skipped" ], "title": "Status", "type": "string" } }, "required": [ "paragraphs", "state", "status", "model", "generated_at", "sources" ], "title": "ReportOut", "type": "object" }, "SourceAdminV1": { "examples": [ { "aggregator": false, "api_key_env": "GUARDIAN_API_KEY", "api_key_set": true, "enabled": true, "first_party": false, "health": { "consecutive_failures": 0, "daily_request_budget": 200, "enabled": true, "id": "guardian-world", "items_last_run": 20, "items_per_day": 42.3, "last_attempt_at": "2026-10-12T08:30:00Z", "last_success_at": "2026-10-12T08:30:00Z", "name": "Guardian world", "next_fetch_at": "2026-10-12T09:00:00Z", "profiles": [ "market-monitor" ], "reads_this_month": 0, "requests_today": 12, "spend_this_month_usd": 0.0, "state": "ok", "type": "guardian" }, "id": "guardian-world", "limits": { "daily_request_budget": 200 }, "name": "Guardian world", "params": { "page_size": 20, "section": "world" }, "profiles": [ "market-monitor" ], "refresh_minutes": 30, "tags": [ "world" ], "type": "guardian", "url": "https://content.guardianapis.com/" } ], "properties": { "aggregator": { "title": "Aggregator", "type": "boolean" }, "api_key_env": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Variable name only; the key is never returned.", "title": "Api Key Env" }, "api_key_set": { "description": "Whether that variable is set in the environment.", "title": "Api Key Set", "type": "boolean" }, "enabled": { "title": "Enabled", "type": "boolean" }, "first_party": { "title": "First Party", "type": "boolean" }, "health": { "$ref": "#/components/schemas/SourceHealthV1" }, "id": { "title": "Id", "type": "string" }, "limits": { "additionalProperties": true, "title": "Limits", "type": "object" }, "name": { "title": "Name", "type": "string" }, "params": { "additionalProperties": true, "title": "Params", "type": "object" }, "profiles": { "items": { "type": "string" }, "title": "Profiles", "type": "array" }, "refresh_minutes": { "title": "Refresh Minutes", "type": "integer" }, "removed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Removed At" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "type": { "title": "Type", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "name", "type", "url", "enabled", "refresh_minutes", "tags", "aggregator", "first_party", "params", "api_key_env", "api_key_set", "limits", "removed_at", "profiles", "health" ], "title": "SourceAdminV1", "type": "object" }, "SourceHealthV1": { "examples": [ { "consecutive_failures": 0, "daily_request_budget": 200, "enabled": true, "id": "guardian-world", "items_last_run": 20, "items_per_day": 42.3, "last_attempt_at": "2026-10-12T08:30:00Z", "last_success_at": "2026-10-12T08:30:00Z", "name": "Guardian world", "next_fetch_at": "2026-10-12T09:00:00Z", "profiles": [ "market-monitor" ], "reads_this_month": 0, "requests_today": 12, "spend_this_month_usd": 0.0, "state": "ok", "type": "guardian" } ], "properties": { "auto_disabled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Auto Disabled At" }, "consecutive_failures": { "title": "Consecutive Failures", "type": "integer" }, "daily_request_budget": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Daily Request Budget" }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disabled Reason" }, "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "items_last_run": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Items Last Run" }, "items_per_day": { "description": "Articles stored per day, last 7 days.", "title": "Items Per Day", "type": "number" }, "last_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Attempt At" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "last_success_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Success At" }, "monthly_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Monthly Budget Usd" }, "name": { "title": "Name", "type": "string" }, "next_fetch_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Next Fetch At" }, "profiles": { "items": { "type": "string" }, "title": "Profiles", "type": "array" }, "reads_this_month": { "description": "Paid reads (X posts) this month (UTC).", "title": "Reads This Month", "type": "integer" }, "requests_today": { "description": "API requests today (UTC).", "title": "Requests Today", "type": "integer" }, "spend_this_month_usd": { "title": "Spend This Month Usd", "type": "number" }, "state": { "description": "ok, pending, failing, disabled, auto_disabled or removed.", "title": "State", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "name", "type", "state", "enabled", "auto_disabled_at", "disabled_reason", "last_success_at", "last_attempt_at", "consecutive_failures", "last_error", "next_fetch_at", "items_per_day", "items_last_run", "requests_today", "daily_request_budget", "reads_this_month", "spend_this_month_usd", "monthly_budget_usd", "profiles" ], "title": "SourceHealthV1", "type": "object" }, "SourceIn": { "additionalProperties": false, "examples": [ { "name": "Ars Technica", "profiles": [ "personal-reader" ], "tags": [ "tech" ], "type": "rss", "url": "https://feeds.arstechnica.com/arstechnica/index" }, { "api_key": "GUARDIAN_API_KEY", "daily_request_budget": 200, "name": "Guardian world", "params": { "page_size": 20, "section": "world" }, "profiles": [ "market-monitor" ], "type": "guardian" } ], "properties": { "aggregator": { "default": false, "title": "Aggregator", "type": "boolean" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Environment variable name (`GUARDIAN_API_KEY` or `${...}`).", "title": "Api Key" }, "cost_per_read_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Per Read Usd" }, "daily_request_budget": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Daily Request Budget" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "first_party": { "default": false, "title": "First Party", "type": "boolean" }, "id": { "default": "", "description": "Defaults to a slug of the name.", "title": "Id", "type": "string" }, "max_posts_per_run": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Posts Per Run" }, "monthly_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Monthly Budget Usd" }, "name": { "title": "Name", "type": "string" }, "params": { "additionalProperties": true, "title": "Params", "type": "object" }, "profiles": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Profile slugs; on update, omit to keep the current ones.", "title": "Profiles" }, "refresh_minutes": { "default": 30, "title": "Refresh Minutes", "type": "integer" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "type": { "$ref": "#/components/schemas/SourceType", "default": "rss" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "required": [ "name" ], "title": "SourceIn", "type": "object" }, "SourceType": { "enum": [ "rss", "atom", "web", "api", "guardian", "newsdata", "x" ], "title": "SourceType", "type": "string" }, "SourceV1": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "type": { "title": "Type", "type": "string" }, "url": { "description": "The feed or page this app reads.", "title": "Url", "type": "string" } }, "required": [ "id", "name", "type", "url", "enabled" ], "title": "SourceV1", "type": "object" }, "StoryCardV1": { "examples": [ { "brief": { "basis": "full_text", "bullets": [ { "citations": [], "text": "It ships next year." } ], "generated_at": "2026-10-12T08:30:00Z", "lead": "A chipmaker unveiled an accelerator aimed at AI agents.", "lead_citations": [ { "headline": "...", "index": 1, "source": "The Verge", "url": "..." } ], "model": "qwen3.5-9b", "sources": [], "status": "ok", "style": "brief" }, "first_seen_at": "2026-10-12T08:30:00Z", "id": 42, "last_updated_at": "2026-10-12T08:30:00Z", "published_at": "2026-10-12T08:30:00Z", "snippet": "The company said...", "source_count": 2, "source_names": [ "The Verge", "Ars Technica" ], "title": "Chipmaker unveils agent-ready accelerator", "updated_at": "2026-10-12T08:30:00Z", "url": "https://news.example/story/42", "version": 3 } ], "properties": { "brief": { "anyOf": [ { "$ref": "#/components/schemas/BriefOut" }, { "type": "null" } ] }, "first_seen_at": { "format": "date-time", "title": "First Seen At", "type": "string" }, "id": { "title": "Id", "type": "integer" }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOut" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Url" }, "last_updated_at": { "description": "Newest member article.", "format": "date-time", "title": "Last Updated At", "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the story was first published.", "title": "Published At" }, "report": { "anyOf": [ { "$ref": "#/components/schemas/ReportOut" }, { "type": "null" } ], "description": "Only with `include=full`." }, "snippet": { "description": "The feed's own summary (when `brief` is null).", "title": "Snippet", "type": "string" }, "source_count": { "title": "Source Count", "type": "integer" }, "source_names": { "items": { "type": "string" }, "title": "Source Names", "type": "array" }, "sources": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StorySourceV1" }, "type": "array" }, { "type": "null" } ], "description": "Only with `include=full`: one article per source.", "title": "Sources" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When this version was published.", "title": "Updated At" }, "url": { "description": "The story page in this app.", "title": "Url", "type": "string" }, "version": { "description": "The published version; bumps on every update.", "title": "Version", "type": "integer" } }, "required": [ "id", "version", "title", "url", "published_at", "updated_at", "first_seen_at", "last_updated_at", "image_url", "snippet", "brief", "source_count", "source_names" ], "title": "StoryCardV1", "type": "object" }, "StorySourceV1": { "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country of the outlet's home market (registry or TLD guess; null when unknown).", "title": "Country" }, "groups": { "description": "User-defined outlet tags (the `groups` list in config/outlets.yaml).", "items": { "type": "string" }, "title": "Groups", "type": "array" }, "headline_only": { "default": false, "description": "Stored without text: counted in coverage, never summarized or cited as evidence.", "title": "Headline Only", "type": "boolean" }, "kind": { "default": "unknown", "description": "wire | international | national | local | trade | state | blog | unknown.", "title": "Kind", "type": "string" }, "name": { "description": "The source (outlet) name.", "title": "Name", "type": "string" }, "origin": { "default": "feed", "description": "`feed`: a configured source; `enrichment`: found by web search for this story (it never makes a story visible on its own).", "enum": [ "feed", "enrichment" ], "title": "Origin", "type": "string" }, "outlet": { "default": "", "description": "Outlet name from config/outlets.yaml (the source name or domain when not listed).", "title": "Outlet", "type": "string" }, "published_at": { "format": "date-time", "title": "Published At", "type": "string" }, "publisher": { "default": "", "description": "The primary label: the article URL's domain (`ai.meta.com`).", "title": "Publisher", "type": "string" }, "stance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "This article's stance toward the story's central claim — supports | disputes | adds | neutral | unclear — from the per-source digest (null until perspectives has run).", "title": "Stance" }, "title": { "title": "Title", "type": "string" }, "url": { "description": "The publisher's own permalink (the raw feed URL).", "title": "Url", "type": "string" }, "via": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The aggregator feed (`Hacker News`) when there is one.", "title": "Via" } }, "required": [ "name", "title", "url", "published_at" ], "title": "StorySourceV1", "type": "object" }, "StoryTraceV1": { "examples": [ { "active_llm_ms": 12300, "calls": [ { "attempt": 1, "latency_ms": 4000, "model": "qwen3.5-9b", "purpose": "brief", "queue_wait_ms": 50, "started_at": "2026-10-12T08:30:00Z", "status": "ok" } ], "events": [ { "detail": { "added": 2 }, "finished_at": "2026-10-12T08:30:00Z", "stage": "enrich", "started_at": "2026-10-12T08:30:00Z", "status": "ok" } ], "jobs": [], "llm_wait_ms": 400, "stage_ms": 30000, "story_id": 3, "wall_ms": 420000 } ], "properties": { "active_llm_ms": { "default": 0, "title": "Active Llm Ms", "type": "integer" }, "calls": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Calls", "type": "array" }, "events": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Events", "type": "array" }, "jobs": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Jobs", "type": "array" }, "llm_wait_ms": { "default": 0, "title": "Llm Wait Ms", "type": "integer" }, "stage_ms": { "default": 0, "title": "Stage Ms", "type": "integer" }, "story_id": { "title": "Story Id", "type": "integer" }, "wall_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Wall Ms" } }, "required": [ "story_id" ], "title": "StoryTraceV1", "type": "object" }, "StoryV1": { "examples": [ { "brief": { "basis": "full_text", "bullets": [ { "citations": [], "text": "It ships next year." } ], "generated_at": "2026-10-12T08:30:00Z", "lead": "A chipmaker unveiled an accelerator aimed at AI agents.", "lead_citations": [ { "headline": "...", "index": 1, "source": "The Verge", "url": "..." } ], "model": "qwen3.5-9b", "sources": [], "status": "ok", "style": "brief" }, "context": [ { "angle": "explained", "domain": "wikipedia.org", "note": "Background on the packaging technique the story mentions", "title": "Chiplet - Wikipedia", "url": "https://en.wikipedia.org/wiki/Chiplet" } ], "first_seen_at": "2026-10-12T08:30:00Z", "id": 42, "last_updated_at": "2026-10-12T08:30:00Z", "model": "qwen3.5-9b", "perspectives": { "agreement": [ { "citations": [ 1 ], "text": "Both outlets report the accelerator ships in March." } ], "different_angles": [], "disagreements": [] }, "published_at": "2026-10-12T08:30:00Z", "report_reason": "published before its report", "report_state": "pending", "snippet": "The company said...", "sources": [ { "name": "The Verge", "published_at": "2026-10-12T08:30:00Z", "publisher": "theverge.com", "title": "Chipmaker unveils agent-ready accelerator", "url": "https://www.theverge.com/2026/10/12/chip-launch" } ], "title": "Chipmaker unveils agent-ready accelerator", "updated_at": "2026-10-12T08:30:00Z", "url": "https://news.example/story/42", "version": 3, "versions": { "schema_version": 1, "story": 3 } } ], "properties": { "brief": { "anyOf": [ { "$ref": "#/components/schemas/BriefOut" }, { "type": "null" } ] }, "context": { "description": "Background/context links (related, not the same event). Empty until the context search runs or when it is off.", "items": { "$ref": "#/components/schemas/ContextLinkV1" }, "title": "Context", "type": "array" }, "first_seen_at": { "format": "date-time", "title": "First Seen At", "type": "string" }, "id": { "title": "Id", "type": "integer" }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ImageOut" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Url" }, "last_updated_at": { "format": "date-time", "title": "Last Updated At", "type": "string" }, "model": { "title": "Model", "type": "string" }, "perspectives": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The 'how outlets differ' synthesis ({agreement, disagreements, different_angles}) after the perspectives pass ran with enough sources; null otherwise. Citations are indexes into `sources`.", "title": "Perspectives" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Published At" }, "report": { "anyOf": [ { "$ref": "#/components/schemas/ReportOut" }, { "type": "null" } ], "description": "Paragraphs only when `report_state=ready`." }, "report_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Reason" }, "report_state": { "anyOf": [ { "enum": [ "ready", "pending", "skipped", "failed" ], "type": "string" }, { "type": "null" } ], "description": "null with reports off.", "title": "Report State" }, "snippet": { "title": "Snippet", "type": "string" }, "sources": { "description": "Every member article, oldest first.", "items": { "$ref": "#/components/schemas/StorySourceV1" }, "title": "Sources", "type": "array" }, "then_and_now": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Planner mode: a verified earlier-vs-current quote comparison ({relation, summary, references}) — present only when relation is `changed` or `expanded` and both quotes verified verbatim in their pages.", "title": "Then And Now" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "url": { "title": "Url", "type": "string" }, "version": { "title": "Version", "type": "integer" }, "versions": { "$ref": "#/components/schemas/VersionsV1" } }, "required": [ "id", "version", "title", "url", "published_at", "updated_at", "first_seen_at", "last_updated_at", "image_url", "snippet", "brief", "report", "report_state", "report_reason", "model", "versions", "sources" ], "title": "StoryV1", "type": "object" }, "SyncResult": { "properties": { "profiles_added": { "items": { "type": "string" }, "title": "Profiles Added", "type": "array" }, "skipped_removed": { "description": "Sources removed in the app; left removed.", "items": { "type": "string" }, "title": "Skipped Removed", "type": "array" }, "sources_added": { "items": { "type": "string" }, "title": "Sources Added", "type": "array" }, "sources_linked": { "description": "`profile/source` links added for existing sources.", "items": { "type": "string" }, "title": "Sources Linked", "type": "array" }, "topics_added": { "description": "`profile/topic`.", "items": { "type": "string" }, "title": "Topics Added", "type": "array" } }, "title": "SyncResult", "type": "object" }, "TelemetrySummaryV1": { "examples": [ { "app_version": "abc1234", "config_hash": "0a1b2c3d4e5f", "funnel": [ { "count": 4, "name": "stories formed", "rate": 0.5 } ], "hours": 24.0, "insights": [ "Most LLM time goes to brief." ], "llm": { "busy_ms": 40000, "calls": 12, "categories": { "interpretation": 2, "summarization": 10 }, "completion_tokens": 1200, "config_hashes": [ "0a1b2c3d4e5f" ], "failed": 0, "invalid": 1, "prompt_tokens": 9000, "queue_wait_ms": 300, "utilization": 0.0004, "versions": [ "abc1234" ] }, "since": "2026-10-12T08:30:00Z", "stages": [] } ], "properties": { "app_version": { "default": "", "title": "App Version", "type": "string" }, "config_hash": { "default": "", "title": "Config Hash", "type": "string" }, "funnel": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Funnel", "type": "array" }, "hours": { "title": "Hours", "type": "number" }, "insights": { "default": [], "items": { "type": "string" }, "title": "Insights", "type": "array" }, "llm": { "additionalProperties": true, "default": {}, "title": "Llm", "type": "object" }, "since": { "title": "Since", "type": "string" }, "stages": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Stages", "type": "array" } }, "required": [ "since", "hours" ], "title": "TelemetrySummaryV1", "type": "object" }, "TestFetchResult": { "properties": { "detected_type": { "anyOf": [ { "$ref": "#/components/schemas/SourceType" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "item_count": { "title": "Item Count", "type": "integer" }, "items": { "description": "The five newest items.", "items": { "$ref": "#/components/schemas/TestItem" }, "title": "Items", "type": "array" }, "latency_ms": { "title": "Latency Ms", "type": "integer" }, "ok": { "title": "Ok", "type": "boolean" }, "status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status of the (first) request.", "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Feed title (or the API source's name).", "title": "Title" } }, "required": [ "ok", "status", "latency_ms", "title", "item_count", "items" ], "title": "TestFetchResult", "type": "object" }, "TestItem": { "properties": { "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Published At" }, "title": { "title": "Title", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "required": [ "title", "url", "published_at" ], "title": "TestItem", "type": "object" }, "TopicV1": { "examples": [ { "enabled": true, "exclude_keywords": [], "id": 3, "include_keywords": [ "ai", "llm" ], "name": "AI", "position": 0, "source_ids": [] } ], "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "exclude_keywords": { "items": { "type": "string" }, "title": "Exclude Keywords", "type": "array" }, "id": { "title": "Id", "type": "integer" }, "include_keywords": { "items": { "type": "string" }, "title": "Include Keywords", "type": "array" }, "name": { "title": "Name", "type": "string" }, "position": { "title": "Position", "type": "integer" }, "source_ids": { "description": "Only these sources; empty = all of the profile's.", "items": { "type": "string" }, "title": "Source Ids", "type": "array" } }, "required": [ "id", "name", "include_keywords", "exclude_keywords", "source_ids", "position", "enabled" ], "title": "TopicV1", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" }, "VersionV1": { "examples": [ { "api_version": "1", "app_version": "0.1.0", "schema_version": 1 } ], "properties": { "api_version": { "title": "Api Version", "type": "string" }, "app_version": { "title": "App Version", "type": "string" }, "schema_version": { "description": "Version of the stored story documents.", "title": "Schema Version", "type": "integer" } }, "required": [ "api_version", "app_version", "schema_version" ], "title": "VersionV1", "type": "object" }, "VersionsV1": { "properties": { "schema_version": { "description": "Version of the stored story document.", "title": "Schema Version", "type": "integer" }, "story": { "description": "The published story version (as in events).", "title": "Story", "type": "integer" } }, "required": [ "story", "schema_version" ], "title": "VersionsV1", "type": "object" } }, "securitySchemes": { "APIKeyHeader": { "description": "The API key.", "in": "header", "name": "X-API-Key", "type": "apiKey" }, "HTTPBearer": { "description": "`Authorization: Bearer `", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Published stories and resumable story events. Within v1 changes are additive only; breaking changes go to /api/v2.", "title": "Discover Feed public API", "version": "1" }, "openapi": "3.1.0", "paths": { "/api/v1/admin/enrich/status": { "get": { "description": "Admin key. Is the worker alive, what is waiting, has the scheduled job run?", "operationId": "admin_enrich_status_api_v1_admin_enrich_status_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichStatusV1" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Enrichment worker health: thread, queue, provider requests, scheduled job", "tags": [ "v1", "v1-admin" ] } }, "/api/v1/admin/telemetry/funnel": { "get": { "description": "The ingest -> publish funnel with failure reasons and retries (admin key).", "operationId": "telemetry_funnel_api_v1_admin_telemetry_funnel_get", "parameters": [ { "in": "query", "name": "hours", "required": false, "schema": { "default": 168, "maximum": 2160, "minimum": 0.1, "title": "Hours", "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Telemetry Funnel", "tags": [ "v1", "v1-admin" ] } }, "/api/v1/admin/telemetry/llm": { "get": { "description": "LLM usage: calls, tokens, queue wait, per-purpose table, slowest (admin key).", "operationId": "telemetry_llm_api_v1_admin_telemetry_llm_get", "parameters": [ { "in": "query", "name": "hours", "required": false, "schema": { "default": 24, "maximum": 720, "minimum": 0.1, "title": "Hours", "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmStatsV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Telemetry Llm", "tags": [ "v1", "v1-admin" ] } }, "/api/v1/admin/telemetry/stories/{story_id}/trace": { "get": { "description": "One story's full trace: stage events and LLM calls (admin key).", "operationId": "telemetry_trace_api_v1_admin_telemetry_stories__story_id__trace_get", "parameters": [ { "in": "path", "name": "story_id", "required": true, "schema": { "title": "Story Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryTraceV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Telemetry Trace", "tags": [ "v1", "v1-admin" ] } }, "/api/v1/admin/telemetry/summary": { "get": { "description": "System summary: stages, LLM totals and funnel for the window (admin key).", "operationId": "telemetry_summary_api_v1_admin_telemetry_summary_get", "parameters": [ { "in": "query", "name": "hours", "required": false, "schema": { "default": 24, "maximum": 720, "minimum": 0.1, "title": "Hours", "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetrySummaryV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Telemetry Summary", "tags": [ "v1", "v1-admin" ] } }, "/api/v1/alert-rules/{rule_id}/preview": { "post": { "operationId": "preview_alert_rule_api_v1_alert_rules__rule_id__preview_post", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Articles of the last 7 days a rule matches (sends nothing; admin)", "tags": [ "v1" ] } }, "/api/v1/chat": { "get": { "operationId": "chat_status_api_v1_chat_get", "parameters": [ { "description": "Default: the worker's profile.", "in": "query", "name": "profile", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default: the worker's profile.", "title": "Profile" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatStatusV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Is story Q&A available?", "tags": [ "v1" ] } }, "/api/v1/conversations/{conversation_id}": { "delete": { "operationId": "delete_conversation_api_v1_conversations__conversation_id__delete", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Delete a conversation", "tags": [ "v1" ] }, "get": { "operationId": "get_conversation_api_v1_conversations__conversation_id__get", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "A conversation with its messages", "tags": [ "v1" ] } }, "/api/v1/health": { "get": { "operationId": "health_api_v1_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthV1" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Liveness and database check", "tags": [ "v1" ] } }, "/api/v1/profiles": { "get": { "operationId": "list_profiles_api_v1_profiles_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ProfileV1" }, "title": "Response List Profiles Api V1 Profiles Get", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "All profiles", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}": { "get": { "operationId": "get_profile_api_v1_profiles__slug__get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "One profile", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/alert-rules": { "get": { "operationId": "list_alert_rules_api_v1_profiles__slug__alert_rules_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AlertRuleV1" }, "title": "Response List Alert Rules Api V1 Profiles Slug Alert Rules Get", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "A profile's alert rules", "tags": [ "v1" ] }, "post": { "operationId": "create_alert_rule_api_v1_profiles__slug__alert_rules_post", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleIn" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Create an alert rule (admin)", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/alert-rules/{rule_id}": { "delete": { "operationId": "delete_alert_rule_api_v1_profiles__slug__alert_rules__rule_id__delete", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "integer" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Delete an alert rule (admin)", "tags": [ "v1" ] }, "put": { "operationId": "update_alert_rule_api_v1_profiles__slug__alert_rules__rule_id__put", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Replace an alert rule (admin)", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/feed": { "get": { "operationId": "profile_feed_api_v1_profiles__slug__feed_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "description": "Topic id; omit for the whole profile.", "in": "query", "name": "topic", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Topic id; omit for the whole profile.", "title": "Topic" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 24, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "`next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`next_cursor` of the previous page.", "title": "Cursor" } }, { "description": "Only stories first published after this time.", "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only stories first published after this time.", "title": "Since" } }, { "description": "Only stories whose current version was published after this time.", "in": "query", "name": "updated_since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only stories whose current version was published after this time.", "title": "Updated Since" } }, { "description": "`full` adds `report` and `sources`.", "in": "query", "name": "include", "required": false, "schema": { "default": "card", "description": "`full` adds `report` and `sources`.", "enum": [ "card", "full" ], "title": "Include", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Published stories, newest update first", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/feed.atom": { "get": { "description": "Title = headline; content = the brief's lead and bullets; links to the story page\n(`alternate`) and to each source (`related`).", "operationId": "profile_atom_api_v1_profiles__slug__feed_atom_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "description": "Topic id; omit for the whole profile.", "in": "query", "name": "topic", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Topic id; omit for the whole profile.", "title": "Topic" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/atom+xml": {} }, "description": "Atom 1.0" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Atom feed of published stories", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/notifications": { "get": { "operationId": "list_notifications_api_v1_profiles__slug__notifications_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "description": "Only this rule.", "in": "query", "name": "rule_id", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Only this rule.", "title": "Rule Id" } }, { "description": "Only this status.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "enum": [ "queued", "sent", "failed", "held", "digested" ], "type": "string" }, { "type": "null" } ], "description": "Only this status.", "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/NotificationV1" }, "title": "Response List Notifications Api V1 Profiles Slug Notifications Get", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "The notification log, newest first", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/sources.opml": { "get": { "operationId": "export_opml_api_v1_profiles__slug__sources_opml_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "text/x-opml": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Export a profile's feeds as OPML", "tags": [ "v1" ] }, "post": { "operationId": "import_opml_api_v1_profiles__slug__sources_opml_post", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "text/x-opml": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpmlImportV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import feeds from OPML (request body: the OPML document)", "tags": [ "v1" ] } }, "/api/v1/profiles/{slug}/topics": { "get": { "operationId": "list_topics_api_v1_profiles__slug__topics_get", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TopicV1" }, "title": "Response List Topics Api V1 Profiles Slug Topics Get", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "A profile's topics", "tags": [ "v1" ] } }, "/api/v1/source-catalog": { "get": { "operationId": "source_catalog_api_v1_source_catalog_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CatalogEntryV1" }, "title": "Response Source Catalog Api V1 Source Catalog Get", "type": "array" } } }, "description": "Successful Response" } }, "summary": "Starter feeds", "tags": [ "v1" ] } }, "/api/v1/sources": { "get": { "operationId": "list_sources_api_v1_sources_get", "parameters": [ { "description": "Also list removed sources.", "in": "query", "name": "include_removed", "required": false, "schema": { "default": false, "description": "Also list removed sources.", "title": "Include Removed", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SourceAdminV1" }, "title": "Response List Sources Api V1 Sources Get", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List sources", "tags": [ "v1" ] }, "post": { "operationId": "create_source_api_v1_sources_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceIn" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Add a source (an identical existing source is shared instead)", "tags": [ "v1" ] } }, "/api/v1/sources/discover": { "post": { "operationId": "discover_api_v1_sources_discover_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FeedCandidate" }, "title": "Response Discover Api V1 Sources Discover Post", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Find the feeds of a site (HTML ) or confirm a feed URL", "tags": [ "v1" ] } }, "/api/v1/sources/health": { "get": { "operationId": "sources_health_api_v1_sources_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SourceHealthV1" }, "title": "Response Sources Health Api V1 Sources Health Get", "type": "array" } } }, "description": "Successful Response" } }, "summary": "Fetch health, budgets and spend of every source", "tags": [ "v1" ] } }, "/api/v1/sources/sync-yaml": { "post": { "operationId": "sync_yaml_api_v1_sources_sync_yaml_post", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncResult" } } }, "description": "Successful Response" } }, "summary": "Add profiles, sources and topics from the YAML that the DB lacks (never deletes)", "tags": [ "v1" ] } }, "/api/v1/sources/test": { "post": { "operationId": "test_fetch_api_v1_sources_test_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestFetchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Fetch a source once without saving anything", "tags": [ "v1" ] } }, "/api/v1/sources/{source_id}": { "delete": { "operationId": "delete_source_api_v1_sources__source_id__delete", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Remove a source (stops fetching; its articles and stories are kept)", "tags": [ "v1" ] }, "get": { "operationId": "get_source_api_v1_sources__source_id__get", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "One source", "tags": [ "v1" ] }, "put": { "operationId": "update_source_api_v1_sources__source_id__put", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Edit a source", "tags": [ "v1" ] } }, "/api/v1/sources/{source_id}/disable": { "post": { "operationId": "disable_source_api_v1_sources__source_id__disable_post", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Disable", "tags": [ "v1" ] } }, "/api/v1/sources/{source_id}/enable": { "post": { "operationId": "enable_source_api_v1_sources__source_id__enable_post", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Enable", "tags": [ "v1" ] } }, "/api/v1/sources/{source_id}/restore": { "post": { "operationId": "restore_source_api_v1_sources__source_id__restore_post", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceAdminV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Undelete", "tags": [ "v1" ] } }, "/api/v1/stories/{story_id}": { "get": { "operationId": "get_story_api_v1_stories__story_id__get", "parameters": [ { "in": "path", "name": "story_id", "required": true, "schema": { "title": "Story Id", "type": "integer" } }, { "description": "Only members from this profile's sources.", "in": "query", "name": "profile", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only members from this profile's sources.", "title": "Profile" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryV1" } } }, "description": "Successful Response" }, "301": { "description": "Merged into another story (follow `Location`)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "One published story", "tags": [ "v1" ] } }, "/api/v1/stories/{story_id}/ask": { "post": { "description": "Answers come only from the story's numbered sources, with `[n]` citations, checked\nafterwards (`done.verification`). Unpublished stories are 404.", "operationId": "ask_api_v1_stories__story_id__ask_post", "parameters": [ { "in": "path", "name": "story_id", "required": true, "schema": { "title": "Story Id", "type": "integer" } }, { "description": "Whose `llm.chat` answers; default: the worker's.", "in": "query", "name": "profile", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Whose `llm.chat` answers; default: the worker's.", "title": "Profile" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskV1" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": {} }, "description": "`text/event-stream`, in this order:\n- `meta` `{conversation_id, message_id, model}`\n- `waiting` `{reason, message}` (only while the model is busy with background work)\n- `token` `{text}` (one per streamed chunk)\n- `citations` `{citations: [{index, article_id, source, publisher, via, headline, url}]}`\n- `done` `{verification: {verified, refusal, cited, checks}, tokens, latency_ms,\n time_to_first_token_ms, tokens_per_second, finish_reason, model}`\n- or, instead of `citations`/`done`, `error` `{reason, message, detail, partial}` with\n `reason` one of `timeout`, `model_busy`, `unreachable`, `upstream_error`, `empty_output`,\n `http_`, `story_unavailable`. A partial answer is stored as `incomplete`.\n\nClosing the connection stops generation upstream." }, "404": { "description": "Story not published, or unknown conversation." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "No chat endpoint is configured for the profile." } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Ask a follow-up question (streams the answer)", "tags": [ "v1" ] } }, "/api/v1/stories/{story_id}/followups": { "get": { "operationId": "followups_api_v1_stories__story_id__followups_get", "parameters": [ { "in": "path", "name": "story_id", "required": true, "schema": { "title": "Story Id", "type": "integer" } }, { "description": "Default: the worker's profile.", "in": "query", "name": "profile", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default: the worker's profile.", "title": "Profile" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowupsV1" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Up to 3 suggested follow-up questions", "tags": [ "v1" ] } }, "/api/v1/stream": { "get": { "description": "Events `story.published`, `story.updated`, `story.retracted` with\n`id: ` and `data: {\"id\", \"type\", \"story_id\", \"version\", \"profiles\"[, \"story\"]}`, and\n`alert.fired` (`data` adds `\"rule\", \"article_id\", \"matched\"`; sent for unpublished\nstories too, never with story content; not filtered by `topic`);\nfirst a `hello` event (`latest_id`), a `heartbeat` event every `heartbeat` seconds and a\n`retry:` hint. Reconnect with `Last-Event-ID` (or `since_id`) to get every event you\nmissed (kept `summaries.event_retention_days`). Listening never starts generation.", "operationId": "stream_api_v1_stream_get", "parameters": [ { "description": "Only this profile's stories.", "in": "query", "name": "profile", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this profile's stories.", "title": "Profile" } }, { "description": "Only this topic (needs `profile`).", "in": "query", "name": "topic", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Only this topic (needs `profile`).", "title": "Topic" } }, { "description": "`card`/`full` add the story (as in the feed) to each event.", "in": "query", "name": "include", "required": false, "schema": { "default": "id", "description": "`card`/`full` add the story (as in the feed) to each event.", "enum": [ "id", "card", "full" ], "title": "Include", "type": "string" } }, { "description": "Replay stored events after this id.", "in": "query", "name": "since_id", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Replay stored events after this id.", "title": "Since Id" } }, { "description": "Seconds between pings.", "in": "query", "name": "heartbeat", "required": false, "schema": { "default": 15, "description": "Seconds between pings.", "exclusiveMinimum": 0, "maximum": 300, "title": "Heartbeat", "type": "number" } }, { "description": "Sent by EventSource on reconnect; wins over since_id.", "in": "header", "name": "last-event-id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sent by EventSource on reconnect; wins over since_id.", "title": "Last-Event-Id" } } ], "responses": { "200": { "content": { "text/event-stream": {} }, "description": "SSE" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "Story events (Server-Sent Events), resumable", "tags": [ "v1" ] } }, "/api/v1/version": { "get": { "operationId": "get_version_api_v1_version_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionV1" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyHeader": [] } ], "summary": "API and app versions", "tags": [ "v1" ] } } } }