Agentic News Briefing API

openapi: 3.2.0
info:
  title: Agentic News Ai Briefing API
  version: 1.0.0
  contact:
    name: Agentic News
    url: https://agentic-news.ai
  description: 'Operations tagged Briefing across 2 of this provider''s published API definitions: openapi.json, agentic-news-ai-openapi.json. Each path carries the servers of the definition it was published in.'
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.
paths:
  /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
    servers:
    - url: https://api.agentic-news.ai
      description: Production
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_...'
externalDocs:
  description: MCP connection guide and full documentation
  url: https://agentic-news.ai/settings/api-keys
x-refined-from:
- openapi.json
- agentic-news-ai-openapi.json