{"openapi":"3.1.0","info":{"title":"Agentic News API","description":"AI-powered news aggregation and monitoring. Search stories, read briefings, and manage monitoring agents.\n\n## Authentication\nUse a Bearer token with your API key: `Authorization: Bearer ak_...`. OAuth clients receive revocable `oa_...` access tokens.\nCreate API keys at [agentic-news.ai/settings/api-keys](https://agentic-news.ai/settings/api-keys) or via `POST /api-keys` (requires JWT auth from the web app).\n\n## MCP (Model Context Protocol)\nAI assistants can connect via MCP at `POST /mcp` using Streamable HTTP transport. The MCP server exposes 26 tools covering all API functionality plus feedback, refinements, collections, and lenses. Connect from Claude.ai or ChatGPT via OAuth, or use an API key as Bearer token.\n\n## Rate Limits\n- **300 requests/min** per API key (global)\n- **30 requests/min** for search endpoints\n- **10 requests/min** for write operations\n\n## Quick Start for AI Agents\n1. Get an API key from [agentic-news.ai/settings/api-keys](https://agentic-news.ai/settings/api-keys)\n2. Call `GET /search?q=your+topic` to find stories\n3. Call `GET /briefing` for your personalized daily briefing\n4. Call `GET /alerts?watchId={id}` for stories from a specific agent\n5. Call `POST /watches` to create a monitoring agent\n6. Or connect via MCP for the full 20-tool experience","version":"1.0.0","contact":{"name":"Agentic News","url":"https://agentic-news.ai"}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key or OAuth Access Token","description":"API key starting with \"ak_\" or OAuth access token starting with \"oa_\". Create API keys at agentic-news.ai/settings/api-keys or via POST /api-keys with JWT auth. Pass as: Authorization: Bearer ak_..."}},"schemas":{}},"paths":{"/watches":{"get":{"operationId":"listAgents","summary":"List monitoring agents","tags":["Agents"],"description":"List all monitoring agents (watches) for the authenticated user. Each agent continuously monitors a topic and surfaces matching stories in your briefing.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"watches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["entity","topic"]},"matchQualityThreshold":{"type":"integer","description":"Minimum match quality (33-100)"},"requiredTerms":{"type":"array","items":{"type":"string"},"description":"Must-include terms"},"termsUnmatchable":{"type":"boolean","description":"True when the required terms cannot match ANY article — this agent can never surface a story until they change"},"lensId":{"type":["null","string"],"description":"Assigned lens ID"},"lensName":{"type":["null","string"],"description":"Assigned lens name"},"paused":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}},"count":{"type":"number"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"post":{"operationId":"createAgent","summary":"Create monitoring agent","tags":["Agents"],"description":"Create a new monitoring agent that watches for news about a specific topic or entity. The agent immediately starts matching against existing stories and queues ingestion for fresh content. Be specific in the description for better results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Short agent name (e.g., 'AI regulation')"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What the agent should monitor — be specific for better results"},"kind":{"type":"string","enum":["entity","topic"],"description":"Agent type (default: topic)"},"requiredTerms":{"type":"array","items":{"type":"string"},"description":"Must-include terms — stories must contain at least one of these in title or body. Geographic terms are auto-populated if not provided."},"matchQualityThreshold":{"type":"integer","minimum":33,"maximum":100,"description":"Minimum match quality score (33-100, default 45). Higher = fewer but more relevant."},"language":{"type":"string","minLength":2,"maxLength":5,"description":"ISO 639-1 language code (default: en)"}}},"example":{"name":"Tesla EV News","description":"Electric vehicle industry news about Tesla, Rivian, and competitors","requiredTerms":["Tesla","Rivian","EV"],"matchQualityThreshold":50}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"watch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string"},"matchQualityThreshold":{"type":"integer"},"requiredTerms":{"type":"array","items":{"type":"string"}},"paused":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/watches/{id}":{"patch":{"operationId":"updateAgent","summary":"Update monitoring agent","tags":["Agents"],"description":"Update an agent's name, description, quality threshold, required terms, or lens assignment. Changing name/description retrains what the agent watches for and triggers re-matching.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"New agent name"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"New agent description"},"lensId":{"type":["string","null"],"format":"uuid","description":"Assign a lens by ID, or null to remove"},"matchQualityThreshold":{"type":"integer","minimum":33,"maximum":100,"description":"Minimum match quality (33-100, default 45)"},"requiredTerms":{"type":"array","items":{"type":"string"},"description":"Must-include terms. Pass [] to clear."}}},"example":{"requiredTerms":["Tesla","Rivian"],"matchQualityThreshold":55}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Agent ID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/clusters/{id}":{"get":{"operationId":"getStoryDetails","summary":"Get story details","tags":["Stories"],"description":"Full details of a news story cluster, including all source articles, topics, entities, and AI-generated analysis. Use the cluster ID from search, briefing, or trending results.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Cluster ID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"canonical":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"}}},"itemCount":{"type":"number"},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"entities":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"collectionIds":{"type":"array","items":{"type":"string"}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"requestId":{"type":"string"}}}}}}}}}}},"/alerts":{"get":{"summary":"Get stories from your agents","tags":["Feed"],"description":"Returns story matches from your monitoring agents with full cluster data, AI-generated hooks, and read state. Filter by agent using `watchId`, sort by date/score/watch name, and paginate. Only shows validated matches (accepted or borderline).","parameters":[{"schema":{"type":"string"},"in":"query","name":"watchId","required":false,"description":"Filter to a specific agent/watch (UUID)"},{"schema":{"type":"integer","default":50},"in":"query","name":"limit","required":false,"description":"Max stories to return (1-100)"},{"schema":{"type":"integer","default":0},"in":"query","name":"offset","required":false,"description":"Pagination offset"},{"schema":{"type":"string","enum":["article-date","match-date","score","watch-name"],"default":"article-date"},"in":"query","name":"sortBy","required":false,"description":"Sort order"},{"schema":{"type":"string","enum":["all","read","unread"],"default":"all"},"in":"query","name":"readFilter","required":false,"description":"Filter by read status"},{"schema":{"type":"integer"},"in":"query","name":"minThreshold","required":false,"description":"Minimum match score (0-100). Defaults to agent's configured threshold."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"skipCount","required":false,"description":"Skip expensive count query"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"cluster":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"canonical":{"type":["null","object"],"additionalProperties":true,"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string"}}},"itemCount":{"type":"integer"},"entities":{"type":"array","items":{"type":"string"},"description":"Entity names (backward-compatible)"},"structuredEntities":{"type":"array","description":"Structured entity data with names, types, and optional URLs","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["company","product","person","organization","technology","location","unknown"]},"url":{"type":"string","description":"Entity website URL (when available)"}}}},"topics":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"isRead":{"type":"boolean"},"lensStatus":{"type":"string"},"lensGeneratedAt":{"type":["null","string"]},"lensError":{"type":["null","string"]},"collectionIds":{"type":"array","items":{"type":"string"}},"hook":{"type":["null","string"]},"preview":{"type":["null","string"]}}},"watch":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"kind":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]}}},"score":{"type":"number","description":"Raw match score (0.0-1.0)"},"matchQuality":{"type":"integer","description":"Match quality (0-100), maps to the agent's quality threshold"},"verdict":{"type":["null","string"]},"verdictReasoning":{"type":["null","string"],"description":"Stage-1 Devil's-Advocate verdict explanation, suitable for surfacing as 'Why I picked this' on a card."},"digestWorthy":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"additionalProperties":true}},"total":{"type":["null","integer"]},"hasMore":{"type":"boolean"},"offset":{"type":"integer"},"limit":{"type":"integer"},"currentThreshold":{"type":"integer"},"nextTier":{"type":["null","object"],"additionalProperties":true,"description":"Next quality tier suggestion, or null"},"hasReadHistory":{"type":"boolean","description":"Whether the user has any read history"},"lastReadAt":{"type":["null","string"],"description":"ISO time of the user's most recent story read, or null"},"serverNow":{"type":"string","description":"Server clock at response time; compare lastReadAt against THIS, never the browser's clock"},"validating":{"type":"boolean","description":"True if matches are still being validated by LLM"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}}},"/alerts/count":{"get":{"summary":"Count stories","tags":["Feed"],"description":"Lightweight count of stories matching filters. Use for pagination or badge counts.","parameters":[{"schema":{"type":"string"},"in":"query","name":"watchId","required":false,"description":"Filter to a specific agent/watch (UUID)"},{"schema":{"type":"string","enum":["all","read","unread"],"default":"all"},"in":"query","name":"readFilter","required":false},{"schema":{"type":"integer"},"in":"query","name":"minThreshold","required":false,"description":"Minimum match score (0-100)"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}}},"/alerts/away-banner-shown":{"post":{"summary":"Record that the while-you-were-away banner was shown to this reader","tags":["Feed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"awayHours":{"type":"integer","minimum":0},"unreadCount":{"type":"integer","minimum":0}},"required":["awayHours"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"204":{"description":"Default Response"},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}}},"/alerts/per-watch-unread-counts":{"get":{"summary":"Unread counts per agent","tags":["Feed"],"description":"Returns a map of agent/watch IDs to their unread story counts. Useful for building navigation with badge counts.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer"}}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}}},"/alerts/{id}/read":{"post":{"operationId":"markAlertRead","summary":"Mark a story as read","tags":["Feed"],"description":"Marks the story (cluster) behind this alert as read. The `id` is the alert/match ID returned by `GET /alerts`. Optionally pass a `source` to track where the read originated (e.g. 'api', 'mcp').","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","maxLength":32}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"alertId":{"type":"string"},"clusterId":{"type":"string"},"isRead":{"type":"boolean"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}},"delete":{"operationId":"markAlertUnread","summary":"Mark a story as unread","tags":["Feed"],"description":"Clears the read state for the story behind this alert. The `id` is the alert/match ID returned by `GET /alerts`.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"alertId":{"type":"string"},"clusterId":{"type":"string"},"isRead":{"type":"boolean"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"requestId":{"type":"string"},"details":{}},"required":["message","code","statusCode","requestId"]}},"required":["error"]}}}}}}},"/public/examples":{"get":{"operationId":"getTrendingStories","summary":"Get trending stories","tags":["Trending"],"description":"Top trending news stories across all topics. No authentication required. Returns curated recent clusters ranked by source count with AI-generated hooks. 15-minute cache.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"examples":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"topics":{"type":"array","items":{"type":"string"}},"sourceCount":{"type":"number"},"hook":{"type":["string","null"]},"agentLabel":{"type":"string"},"verdictReasoning":{"type":["string","null"]},"url":{"type":["string","null"]}}}},"source":{"type":"string","enum":["live","none"]}}}}}}}}},"/public/transparency":{"get":{"operationId":"getTransparencyStats","summary":"Get Devil's Advocate rejection stats and sample rejections","tags":["Trending"],"description":"Public, no-auth endpoint. Returns the last 24 hours of validation activity and a sample of articles rejected by the Devil's Advocate validator with one-line reasoning. Cached 10 minutes.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"object","properties":{"windowHours":{"type":"number"},"asOf":{"type":"string","format":"date-time"},"accepted":{"type":"number"},"rejected":{"type":"number"},"borderline":{"type":"number"},"rejectionRate":{"type":"number"}}},"samples":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"publisher":{"type":"string"},"publishedAt":{"type":["string","null"],"format":"date-time"},"reasoning":{"type":"string"}}}}}}}}}}}},"/briefing":{"get":{"operationId":"getBriefing","summary":"Get daily briefing","tags":["Briefing"],"description":"Personalized daily news briefing based on your monitoring agents. Returns a hero story, top stories, and overflow stories ranked by relevance with AI-generated hooks and quality scores.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"hero":{"type":["object","null"],"additionalProperties":true,"description":"Top story of the day"},"topStories":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Next 4 top stories"},"overflow":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Additional stories beyond top 5"},"agentSummary":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per-agent match counts"},"totalMatches":{"type":"number"},"reviewCounts":{"type":["object","null"],"description":"Last-24h moat stats for this user. reviewed=total above-threshold matches validated; rejected=how many Stage-1 argued against; delivered=stories shown. Surface 'We reviewed N and argued against X — here are the M that survived.'","properties":{"reviewed":{"type":"number"},"rejected":{"type":"number"},"delivered":{"type":"number"},"sourcesScanned":{"type":"number","description":"Distinct publishers ingested into the shared pool in the last 24h — the breadth of the net cast before judging. 0 when the count is unavailable (masthead omits the clause)."}}},"rejectedSample":{"type":["object","null"],"description":"ONE concrete argued-down story (title + the validator's reason) backing the count, for the Variant-B masthead. Populated from the user's own most-recent rejection when reviewCounts.rejected > 0; null (count-only masthead) when there is no publishable rejection.","properties":{"title":{"type":"string"},"publisher":{"type":["string","null"]},"reason":{"type":"string"}}},"state":{"type":"string","enum":["no_agents","no_matches_today","processing","few_matches","ready","access_expired"]},"validating":{"type":"boolean","description":"True when above-threshold matches are still pending LLM validation"},"headline":{"type":["string","null"],"description":"AI-generated briefing headline"},"digestDate":{"type":"string","format":"date-time"}}}}}}}}},"/api-keys":{"post":{"operationId":"createApiKey","summary":"Create API key","tags":["API Keys"],"description":"Create a new API key for agent-accessible API access. The full key is returned exactly once — store it securely. Requires JWT authentication.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Label for the key"},"expiresInDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days until expiry (omit for no expiry)"}}}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"Full API key (shown once)"},"keyPrefix":{"type":"string","description":"Display prefix (e.g., \"ak_a1b2...\")"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}}}},"get":{"operationId":"listApiKeys","summary":"List API keys","tags":["API Keys"],"description":"List all API keys for the authenticated user. Returns key prefixes, not full keys.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"revoked":{"type":"boolean"}}}}}}}}}},"/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke API key","tags":["API Keys"],"description":"Revoke an API key by ID. The key is soft-deleted (revoked_at set) and can no longer be used for authentication.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"API key ID to revoke"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/search":{"get":{"operationId":"searchNews","summary":"News search","tags":["Search"],"description":"Search recent news stories. Understands meaning, not just keywords. Public: 3 results max. Authenticated: up to 20. Rate limit: 30 req/min.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":500},"in":"query","name":"q","required":true,"description":"Search query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"in":"query","name":"limit","required":false,"description":"Max results (public: capped at 3)"},{"schema":{"type":"integer","minimum":1,"maximum":30,"default":7},"in":"query","name":"days","required":false,"description":"How far back to search in days"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"sourceCount":{"type":"integer"},"publishedAt":{"type":["string","null"],"format":"date-time"},"publisher":{"type":["string","null"]},"score":{"type":"number","description":"Cosine similarity score (0-1)"}}}},"total":{"type":"integer"}}}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List your webhooks","tags":["Agents"],"description":"Returns all registered webhook endpoints for the authenticated user.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"watchId":{"type":["null","string"]},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":["null","string"]},"lastFailureAt":{"type":["null","string"]},"lastFailureReason":{"type":["null","string"]},"createdAt":{"type":"string"}}}}}}}}}}},"post":{"operationId":"createWebhook","summary":"Register a webhook","tags":["Agents"],"description":"Register a URL to receive POST notifications when matches are validated. Optionally scope to a specific agent (watchId). Set `generateSecret: true` to get an HMAC-SHA256 signing secret (returned only once).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL to receive POST payloads"},"watchId":{"type":"string","description":"Scope to a specific agent (UUID). Omit for all agents."},"events":{"type":"array","items":{"type":"string","enum":["match.validated"]},"default":["match.validated"]},"generateSecret":{"type":"boolean","default":false,"description":"Generate an HMAC-SHA256 signing secret"}}}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"watchId":{"type":["null","string"]},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":["null","string"],"description":"HMAC secret (returned only on creation)"},"createdAt":{"type":"string"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/webhooks/{id}":{"patch":{"operationId":"updateWebhook","summary":"Update a webhook","tags":["Agents"],"description":"Update a webhook's URL, active state, or events. Reactivating resets the failure counter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"events":{"type":"array","items":{"type":"string","enum":["match.validated"]}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"isActive":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"failureCount":{"type":"integer"},"updatedAt":{"type":"string"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","tags":["Agents"],"description":"Permanently removes a webhook registration.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"servers":[{"url":"https://api.agentic-news.ai","description":"Production"}],"tags":[{"name":"Briefing","description":"Your personalized daily news briefing based on your monitoring agents. Returns stories ranked by relevance with AI-generated hooks and briefs. Requires auth."},{"name":"Feed","description":"Your story feed with per-agent filtering, sorting by date/score/watch, read state tracking, and pagination. Use `watchId` to get stories for a specific agent. Requires auth."},{"name":"Stories","description":"Full details of news story clusters including all source articles, topics, entities, and AI analysis. Requires auth."},{"name":"Search","description":"Search recent news by meaning, not just keywords. Works without auth (3 results max) or with auth (up to 20 results). Rate limit: 30 req/min."},{"name":"Trending","description":"Top trending news stories ranked by coverage volume. No authentication required."},{"name":"Agents","description":"Create and manage monitoring agents (watches). Each agent tracks a topic and automatically finds matching stories. Requires auth."},{"name":"API Keys","description":"Create, list, and revoke API keys for programmatic access. Keys use ak_ prefix with SHA-256 hashing. Requires JWT auth (web app session)."}],"externalDocs":{"description":"MCP connection guide and full documentation","url":"https://agentic-news.ai/settings/api-keys"}}