openapi: 3.2.0
info:
  title: Perigon News & Stories API
  description: The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key.
  contact:
    name: Perigon Support
    url: https://docs.perigon.io/
    email: data@perigon.io
  version: 1.0.0
servers:
- url: https://api.perigon.io
  description: Generated server url
security:
- apiKeyAuth: []
tags:
- name: News & Stories
  description: Endpoints for accessing news articles and stories
paths:
  /v1/articles/all:
    get:
      tags:
      - News & Stories
      summary: All Articles
      description: Search and filter all news articles available via the Perigon API. The result includes a list of individual articles that were matched to your specific criteria.
      operationId: search-articles
      parameters:
      - name: q
        in: query
        description: String. Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching.
        required: false
        schema:
          type: string
      - name: title
        in: query
        description: String. Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations.
        required: false
        schema:
          type: string
      - name: desc
        in: query
        description: String. Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching.
        required: false
        schema:
          type: string
      - name: content
        in: query
        description: String. Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching.
        required: false
        schema:
          type: string
      - name: summary
        in: query
        description: String. Search within article summary fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching.
        required: false
        schema:
          type: string
      - name: url
        in: query
        description: String. Search query on the url field. Semantic similar to q parameter. E.g. could be used for querying certain website sections, e.g. source=cnn.com&url=travel.
        required: false
        schema:
          type: string
      - name: articleId
        in: query
        description: String Array. Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: clusterId
        in: query
        description: String Array. Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        in: query
        description: String. Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate).
        required: false
        schema:
          $ref: '#/components/schemas/AllEndpointSortBy'
      - name: page
        in: query
        description: Integer. The specific page of results to retrieve in the paginated response. Starts at 0.
        required: false
        schema:
          maximum: 10000
          minimum: 0
          type: integer
          format: int32
      - name: size
        in: query
        description: Integer. The number of articles to return per page in the paginated response.
        required: false
        schema:
          maximum: 1000
          minimum: 0
          type: integer
          format: int32
      - name: from
        in: query
        description: Date. Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Date. Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: addDateFrom
        in: query
        description: Date. Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: addDateTo
        in: query
        description: Date. Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: refreshDateFrom
        in: query
        description: Date. Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: refreshDateTo
        in: query
        description: Date. Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: medium
        in: query
        description: String Array. Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: source
        in: query
        description: String Array. Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceGroup
        in: query
        description: String Array. Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSourceGroup
        in: query
        description: String Array. Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100).
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSource
        in: query
        description: String Array. Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: watchlist
        in: query
        description: String Array. Filter articles using watchlists of people and companies. Multiple values create an OR filter to include articles mentioning any entity from the specified watchlists.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeWatchlist
        in: query
        description: String Array. Exclude articles mentioning entities from specified watchlists. Multiple values create an AND-exclude filter, removing content mentioning any entity from the specified watchlists.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: paywall
        in: query
        description: Boolean. Filter to show only results where the source has a paywall (true) or does not have a paywall (false).
        required: false
        schema:
          type: boolean
      - name: byline
        in: query
        description: String Array. Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: author
        in: query
        description: String Array. Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeAuthor
        in: query
        description: String Array. Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: journalistId
        in: query
        description: String Array. Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeJournalistId
        in: query
        description: String Array. Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: language
        in: query
        description: String Array. Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeLanguage
        in: query
        description: String Array. Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: searchTranslation
        in: query
        description: Boolean. Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields.
        required: false
        schema:
          type: boolean
      - name: label
        in: query
        description: String Array. Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeLabel
        in: query
        description: String Array. Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: category
        in: query
        description: 'String Array. Filter by categories. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. Use ''none'' to search uncategorized articles.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeCategory
        in: query
        description: String Array. Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: topic
        in: query
        description: String Array. Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeTopic
        in: query
        description: String Array. Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: linkTo
        in: query
        description: String. Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses.
        required: false
        schema:
          type: string
      - name: showReprints
        in: query
        description: Boolean. Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites.
        required: false
        schema:
          type: boolean
      - name: reprintGroupId
        in: query
        description: String. Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content.
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: String Array. Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeCity
        in: query
        description: String Array. A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: area
        in: query
        description: String Array. Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: state
        in: query
        description: String Array. Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeState
        in: query
        description: String Array. A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states).
        required: false
        schema:
          type: array
          items:
            type: string
      - name: county
        in: query
        description: String Array. A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeCounty
        in: query
        description: String Array. Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter
        required: false
        schema:
          type: array
          items:
            type: string
      - name: locationsCountry
        in: query
        description: String Array. Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: country
        in: query
        description: String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeLocationsCountry
        in: query
        description: String Array. Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: location
        in: query
        description: 'String Array. Return all articles that have the specified location. Location attributes are delimited by '':'' between key and value, and ''::'' between attributes. Example: ''city:New York::state:NY''.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: lat
        in: query
        description: Float. Latitude of the center point to search places
        required: false
        schema:
          maximum: 90
          minimum: -90
          type: number
          format: double
      - name: lon
        in: query
        description: Float. Longitude of the center point to search places
        required: false
        schema:
          maximum: 180
          minimum: -180
          type: number
          format: double
      - name: maxDistance
        in: query
        description: Float. Maximum distance (in km) from starting point to search articles by tagged places
        required: false
        schema:
          maximum: 300
          minimum: 1
          type: number
          format: double
      - name: sourceCity
        in: query
        description: String Array. Find articles published by sources that are located within a given city.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSourceCity
        in: query
        description: String Array. Excludes articles published by sources that are located within the specified cities.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceCounty
        in: query
        description: String Array. Find articles published by sources that are located within a given county.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSourceCounty
        in: query
        description: String Array. Excludes articles published by sources that are located within the specified counties.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceCountry
        in: query
        description: String Array. Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc).
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSourceCountry
        in: query
        description: String Array. Excludes articles published by sources that are located within the specified countries. Must be 2 character country codes (e.g., us, gb).
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceState
        in: query
        description: String Array. Find articles published by sources that are located within a given state.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeSourceState
        in: query
        description: String Array. Excludes articles published by sources that are located within the specified states.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceLat
        in: query
        description: Float. Latitude of the center point to search articles created by local publications.
        required: false
        schema:
          maximum: 90
          minimum: -90
          type: number
          format: double
      - name: sourceLon
        in: query
        description: Float. Longitude of the center point to search articles created by local publications.
        required: false
        schema:
          maximum: 180
          minimum: -180
          type: number
          format: double
      - name: sourceMaxDistance
        in: query
        description: Float. Maximum distance from starting point to search articles created by local publications.
        required: false
        schema:
          maximum: 300
          minimum: 1
          type: number
          format: double
      - name: personWikidataId
        in: query
        description: String Array. Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludePersonWikidataId
        in: query
        description: String Array. Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: personName
        in: query
        description: String Array. Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludePersonName
        in: query
        description: String Array. Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyId
        in: query
        description: String Array. Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeCompanyId
        in: query
        description: String Array. Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyName
        in: query
        description: String. Filter articles by company name mentions. Performs an exact match on company names.
        required: false
        schema:
          type: string
      - name: companyDomain
        in: query
        description: String Array. Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeCompanyDomain
        in: query
        description: String Array. Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companySymbol
        in: query
        description: String Array. Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyIsin
        in: query
        description: String Array. Filter articles by company ISIN codes (International Securities Identification Numbers). For available company entities and their ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: companySymbolIsin
        in: query
        description: String Array. Filter articles by ISIN codes on company ticker listings (symbols.isin). Distinct from companyIsin, which matches the company-level ISIN. For available company entities and their listing ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: excludeCompanyIsin
        in: query
        description: String Array. Exclude articles related to companies with specific ISIN codes. Creates an AND-exclude filter to remove content about these companies. For available company entities and their ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: excludeCompanySymbolIsin
        in: query
        description: String Array. Exclude articles related to companies whose ticker listings have these ISIN codes (symbols.isin). Distinct from excludeCompanyIsin, which matches the company-level ISIN. For available company entities and their listing ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: excludeCompanySymbol
        in: query
        description: String Array. A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: showNumResults
        in: query
        description: Boolean. Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles.
        required: false
        schema:
          type: boolean
      - name: positiveSentimentFrom
        in: query
        description: Float. Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: positiveSentimentTo
        in: query
        description: Float. Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentFrom
        in: query
        description: Float. Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentTo
        in: query
        description: Float. Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentFrom
        in: query
        description: Float. Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentTo
        in: query
        description: Float. Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: taxonomy
        in: query
        description: 'String Array. Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://docs.cloud.google.com/natural-language/docs/categories#version_2)'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: prefixTaxonomy
        in: query
        description: 'String. Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance'
        required: false
        schema:
          type: string
      - name: showHighlighting
        in: query
        description: Boolean. When set to true, enables text highlighting in search results.
        required: false
        schema:
          type: boolean
      - name: highlightFragmentSize
        in: query
        description: Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified.
        required: false
        schema:
          type: integer
          format: int32
      - name: highlightNumFragments
        in: query
        description: Integer. Controls the maximum number of highlighted fragments to return per field.
        required: false
        schema:
          type: integer
          format: int32
      - name: highlightPreTag
        in: query
        description: String. Defines the HTML tag that appears before highlighted text. Defaults to '<em>' if not specified.
        required: false
        schema:
          type: string
      - name: highlightPostTag
        in: query
        description: String. Defines the HTML tag that appears after highlighted text. Defaults to '</em>' if not specified.
        required: false
        schema:
          type: string
      - name: highlightQ
        in: query
        description: 'String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query ''q=climate change'' with ''highlightQ=renewable OR solar'' will highlight terms ''renewable'' and ''solar'' in results about climate change.'
        required: false
        schema:
          type: string
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuerySearchResult'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/articles/refresh/jobs:
    post:
      tags:
      - News & Stories
      summary: Submit an article refresh job
      description: Submits article ids for background refresh. Articles resolvable from a fresh cache are returned immediately; the rest are scheduled for processing. Poll the job status endpoint for results.
      operationId: submit-article-refresh-job
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleRefreshSubmitRequest'
        required: true
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '404':
          description: 404 - One or more article ids do not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleRefreshJobResponse'
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/articles/refresh/jobs/{id}:
    get:
      tags:
      - News & Stories
      summary: Get article refresh job status
      description: Returns the job status together with whatever per-article results have been computed so far. Results are immutable snapshots taken when each article was processed.
      operationId: get-article-refresh-job
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '404':
          description: 404 - Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleRefreshJobResponse'
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/articles/refresh/peek:
    post:
      tags:
      - News & Stories
      summary: Peek cached article refresh data
      description: Returns whatever refreshed article data is already cached, on a best-effort basis, without scheduling any processing or creating a job.
      operationId: peek-article-refresh
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleRefreshSubmitRequest'
        required: true
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleRefreshPeekResponse'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/stories/all:
    get:
      tags:
      - News & Stories
      summary: Stories
      description: 'Track evolving narratives and top news headlines with the ''**Stories**'' endpoint — it returns structured clusters of related articles with summaries, key points, sentiment scores, and metadata on top people, companies, topics, countries, and categories. Use it to monitor how news stories develop over time, who and what they impact, and where they''re gaining traction globally.


        Each story represents a cluster of related articles grouped during processing. Articles are assigned to a single story, identified by the `clusterId` field. Once a story reaches five articles, a story title is automatically generated based on its content. Stories update as new coverage is processed and key details evolve.


        To fetch all articles within a specific story, query the `/articles/all` endpoint using the `clusterId` parameter.'
      operationId: search-stories
      parameters:
      - name: q
        in: query
        description: String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching.
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations.
        required: false
        schema:
          type: string
      - name: clusterId
        in: query
        description: String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeClusterId
        in: query
        description: String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sortBy
        in: query
        description: String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints).
        required: false
        schema:
          $ref: '#/components/schemas/ClustersListSortBy'
      - name: page
        in: query
        description: Integer. The specific page of results to retrieve in the paginated response. Starts at 0.
        required: false
        schema:
          maximum: 10000
          minimum: 0
          type: integer
          format: int32
      - name: size
        in: query
        description: Integer. The number of articles to return per page in the paginated response.
        required: false
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
      - name: from
        in: query
        description: Filter for stories created on or after this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Filter for stories created on or before this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: initializedFrom
        in: query
        description: Filter for stories initialized on or after this date. A story is initialized when it becomes visible with generated story data.
        required: false
        schema:
          type: string
          format: date-time
      - name: initializedTo
        in: query
        description: Filter for stories initialized on or before this date. A story is initialized when it becomes visible with generated story data.
        required: false
        schema:
          type: string
          format: date-time
      - name: updatedFrom
        in: query
        description: Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines.
        required: false
        schema:
          type: string
          format: date-time
      - name: updatedTo
        in: query
        description: Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines.
        required: false
        schema:
          type: string
          format: date-time
      - name: topic
        in: query
        description: String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: category
        in: query
        description: String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: taxonomy
        in: query
        description: 'String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: source
        in: query
        description: String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceGroup
        in: query
        description: String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: minUniqueSources
        in: query
        description: Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: minSourceDiversity
        in: query
        description: Float. Minimum ratio of unique sources to unique articles (uniqueSources / uniqueCount). Filters out stories dominated by a single publisher. For example, a value of 0.05 requires at least 1 unique source per 20 articles. Not applied by default.
        required: false
        schema:
          maximum: 1
          minimum: 0
          type: number
      - name: personWikidataId
        in: query
        description: String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: personName
        in: query
        description: String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint.
        required: false
        schema:
          type: string
      - name: companyId
        in: query
        description: String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyName
        in: query
        description: String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field.
        required: false
        schema:
          type: string
      - name: companyDomain
        in: query
        description: String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companySymbol
        in: query
        description: String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyIsin
        in: query
        description: String Array. Filter stories by ISIN codes of top mentioned companies (International Securities Identification Numbers). Returns stories where companies with these ISINs appear prominently. For available company entities and their ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: companySymbolIsin
        in: query
        description: String Array. Filter stories by ISIN codes on ticker listings of top mentioned companies (symbols.isin). Distinct from companyIsin, which matches the company-level ISIN. Returns stories where those companies appear prominently. For available company entities and their listing ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: country
        in: query
        description: String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: state
        in: query
        description: String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: city
        in: query
        description: String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: area
        in: query
        description: String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: minClusterSize
        in: query
        description: Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: maxClusterSize
        in: query
        description: Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster.
        required: false
        schema:
          type: integer
          format: int32
      - name: nameExists
        in: query
        description: Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles.
        required: false
        schema:
          type: boolean
      - name: positiveSentimentFrom
        in: query
        description: Filter stories with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: positiveSentimentTo
        in: query
        description: Filter stories with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentFrom
        in: query
        description: Filter stories with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentTo
        in: query
        description: Filter stories with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentFrom
        in: query
        description: Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentTo
        in: query
        description: Filter stories with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: showStoryPageInfo
        in: query
        description: Boolean.
        required: false
        schema:
          type: boolean
      - name: showNumResults
        in: query
        description: Boolean. Show total number of results. By default set to false, will cap result count at 10000.
        required: false
        schema:
          type: boolean
      - name: showDuplicates
        in: query
        description: Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown.
        required: false
        schema:
          type: boolean
      - name: showHighlighting
        in: query
        description: Boolean. When set to true, enables text highlighting in search results.
        required: false
        schema:
          type: boolean
      - name: highlightFragmentSize
        in: query
        description: Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified.
        required: false
        schema:
          type: integer
          format: int32
      - name: highlightNumFragments
        in: query
        description: Integer. Controls the maximum number of highlighted fragments to return per field.
        required: false
        schema:
          type: integer
          format: int32
      - name: highlightPreTag
        in: query
        description: String. Defines the HTML tag that appears before highlighted text. Defaults to '<em>' if not specified.
        required: false
        schema:
          type: string
      - name: highlightPostTag
        in: query
        description: String. Defines the HTML tag that appears after highlighted text. Defaults to '</em>' if not specified.
        required: false
        schema:
          type: string
      - name: highlightQ
        in: query
        description: 'String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query ''q=climate change'' with ''highlightQ=renewable OR solar'' will highlight terms ''renewable'' and ''solar'' in results about climate change.'
        required: false
        schema:
          type: string
      - name: expandArticles
        in: query
        description: Boolean. Preview 5 articles from the cluster.
        required: false
        schema:
          type: boolean
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorySearchResult'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/stories/history:
    get:
      tags:
      - News & Stories
      summary: Story History
      description: Retrieve previous generated versions of stories and their evolving summaries, key points, questions, and changelogs.
      operationId: get-story-history
      parameters:
      - name: clusterId
        in: query
        description: Filter history records by story cluster ID. Multiple values are combined with OR.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: from
        in: query
        description: Filter for history records created on or after this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Filter for history records created on or before this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: sortBy
        in: query
        description: Field used to sort history records in descending order. Accepts createdAt or triggeredAt and defaults to createdAt.
        required: false
        schema:
          type: string
          enum:
          - createdAt
          - triggeredAt
      - name: page
        in: query
        description: Integer. Zero-based page number. From 0 to 10000. See the Pagination section for limitations.
        required: false
        schema:
          maximum: 10000
          minimum: 0
          type: integer
          format: int32
      - name: size
        in: query
        description: Integer. Number of stories results per page, from 0 to 100.
        required: false
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
      - name: changelogExists
        in: query
        description: Filter by whether a history record contains a changelog. Use true to require one or false to require its absence.
        required: false
        schema:
          type: boolean
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryHistoryResult'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/stories/stats:
    get:
      tags:
      - News & Stories
      summary: Story Count Statistics
      description: Count matching stories by their creation time. Results can be grouped by hour, day, week, or month and filtered by supported story attributes.
      operationId: get-story-counts
      parameters:
      - name: q
        in: query
        description: String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching.
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations.
        required: false
        schema:
          type: string
      - name: clusterId
        in: query
        description: String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: excludeClusterId
        in: query
        description: String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: from
        in: query
        description: Filter for stories created on or after this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: Filter for stories created on or before this date. Accepts ISO 8601 or yyyy-mm-dd format.
        required: false
        schema:
          type: string
          format: date-time
      - name: initializedFrom
        in: query
        description: Filter for stories initialized on or after this date. A story is initialized when it becomes visible with generated story data.
        required: false
        schema:
          type: string
          format: date-time
      - name: initializedTo
        in: query
        description: Filter for stories initialized on or before this date. A story is initialized when it becomes visible with generated story data.
        required: false
        schema:
          type: string
          format: date-time
      - name: updatedFrom
        in: query
        description: Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines.
        required: false
        schema:
          type: string
          format: date-time
      - name: updatedTo
        in: query
        description: Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines.
        required: false
        schema:
          type: string
          format: date-time
      - name: topic
        in: query
        description: String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: category
        in: query
        description: String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: taxonomy
        in: query
        description: 'String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: source
        in: query
        description: String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sourceGroup
        in: query
        description: String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: minUniqueSources
        in: query
        description: Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: minSourceDiversity
        in: query
        description: Float. Minimum ratio of unique sources to unique articles (uniqueSources / uniqueCount). Filters out stories dominated by a single publisher. For example, a value of 0.05 requires at least 1 unique source per 20 articles. Not applied by default.
        required: false
        schema:
          maximum: 1
          minimum: 0
          type: number
      - name: personWikidataId
        in: query
        description: String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: personName
        in: query
        description: String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint.
        required: false
        schema:
          type: string
      - name: companyId
        in: query
        description: String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyName
        in: query
        description: String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field.
        required: false
        schema:
          type: string
      - name: companyDomain
        in: query
        description: String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companySymbol
        in: query
        description: String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: companyIsin
        in: query
        description: String Array. Filter stories by ISIN codes of top mentioned companies (International Securities Identification Numbers). Returns stories where companies with these ISINs appear prominently. For available company entities and their ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: companySymbolIsin
        in: query
        description: String Array. Filter stories by ISIN codes on ticker listings of top mentioned companies (symbols.isin). Distinct from companyIsin, which matches the company-level ISIN. Returns stories where those companies appear prominently. For available company entities and their listing ISINs, consult the /companies endpoint.
        required: false
        schema:
          maxItems: 300
          minItems: 0
          type: array
          items:
            type: string
      - name: country
        in: query
        description: String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: state
        in: query
        description: String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: city
        in: query
        description: String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: area
        in: query
        description: String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: minClusterSize
        in: query
        description: Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles.
        required: false
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: maxClusterSize
        in: query
        description: Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster.
        required: false
        schema:
          type: integer
          format: int32
      - name: nameExists
        in: query
        description: Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles.
        required: false
        schema:
          type: boolean
      - name: positiveSentimentFrom
        in: query
        description: Filter stories with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: positiveSentimentTo
        in: query
        description: Filter stories with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentFrom
        in: query
        description: Filter stories with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: neutralSentimentTo
        in: query
        description: Filter stories with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentFrom
        in: query
        description: Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: negativeSentimentTo
        in: query
        description: Filter stories with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.
        required: false
        schema:
          type: number
          format: float
      - name: showDuplicates
        in: query
        description: Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown.
        required: false
        schema:
          type: boolean
      - name: splitBy
        in: query
        description: Time interval used to group story counts. Accepts hour, day, week, or month and defaults to month.
        required: true
        schema:
          type: string
          default: month
          enum:
          - hour
          - day
          - week
          - month
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatResult'
              example:
                status: 200
                results:
                - date: '2025-07-01T00:00:00Z'
                  numResults: 78032
                - date: '2025-08-01T00:00:00Z'
                  numResults: 24508
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
  /v1/vector/news/all:
    post:
      tags:
      - News & Stories
      summary: News (Vector)
      description: Perform a natural language search over news articles from the past 6 months using semantic relevance. The result includes a list of articles most closely matched to your query intent.
      operationId: vector-search-articles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleSearchParams'
        required: true
      responses:
        '401':
          description: 401 - Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 401
                message: Invalid API key.
                timestamp: 1681338367402
        '200':
          description: 200 - Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesVectorSearchResult'
        '500':
          description: 500 - Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                message: Internal error. Please contact the support to resolve the problem. We apologize for any inconvenience :)
                timestamp: 1681338367402
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                message: Errors during parameter validation.
                timestamp: 1681338367402
        '403':
          description: 403 - Request Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                message: The number of allowed requests is exceeded.
                timestamp: 1681338367402
        '429':
          description: 429 - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 429
                message: Exceeded request rate limit for your account.
                timestamp: 1681338367402
      security:
      - apiKeyAuth: []
components:
  schemas:
    LabelHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Editorial label assigned to the article.
      description: Editorial labels assigned to the article.
    ArticleSearchFilter:
      type: object
      properties:
        articleId:
          type:
          - array
          - 'null'
          description: Filter by specific article identifiers. Accepts either a single ID or an array of IDs. Returns only articles matching these IDs.
          example:
          - ''
          items:
            type: string
        clusterId:
          type:
          - array
          - 'null'
          description: Filter by specific story identifiers. Accepts either a single ID or an array of IDs. Returns only articles belonging to these stories.
          example:
          - ''
          items:
            type: string
        source:
          type:
          - array
          - 'null'
          description: Filter articles by specific publisher domains or subdomains. Accepts either a single domain or an array of domains. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        excludeSource:
          type:
          - array
          - 'null'
          description: Exclude articles from specific publisher domains or subdomains. Accepts either a single domain or an array of domains. Multiple values create an AND-exclude filter.
          example:
          - ''
          items:
            type: string
        sourceGroup:
          type:
          - array
          - 'null'
          description: Filter articles using Perigon's curated publisher bundles (e.g., top100, top25tech). Accepts either a single source group or an array. Multiple values create an OR filter to include articles from any of the specified bundles.
          example:
          - ''
          items:
            type: string
        language:
          type:
          - array
          - 'null'
          description: Filter articles by their language using ISO-639 two-letter codes in lowercase (e.g., en, es, fr). Accepts either a single language code or an array. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        excludeLanguage:
          type:
          - array
          - 'null'
          description: Exclude articles in specific languages using ISO-639 two-letter codes in lowercase. Accepts either a single language code or an array. Multiple values create an AND-exclude filter.
          example:
          - ''
          items:
            type: string
        label:
          type:
          - array
          - 'null'
          description: Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. View our docs for an exhaustive list of labels. Accepts either a single label or an array. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        excludeLabel:
          type:
          - array
          - 'null'
          description: Exclude articles with specific editorial labels. Accepts either a single label or an array. Multiple values create an AND-exclude filter, removing all content with any of these labels.
          example:
          - ''
          items:
            type: string
        taxonomy:
          type:
          - array
          - 'null'
          description: 'Filter by Google Content Categories. Must pass the full hierarchical path of the category. Accepts either a single path or an array. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Multiple values create an OR filter.'
          example:
          - ''
          items:
            type: string
        category:
          type:
          - array
          - 'null'
          description: Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Accepts either a single category or an array. Use none to find uncategorized articles. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        topic:
          type:
          - array
          - 'null'
          description: Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Accepts either a single topic or an array. Topics are more granular than categories, and articles can have multiple topics. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        excludeTopic:
          type:
          - array
          - 'null'
          description: Exclude articles with specific topics. Accepts either a single topic or an array. Multiple values create an AND-exclude filter, removing all content with any of these topics.
          example:
          - ''
          items:
            type: string
        country:
          type:
          - array
          - 'null'
          description: Filter articles by countries they mention using two-letter country codes in lowercase (e.g., us, gb, jp). Accepts either a single country code or an array. Multiple values create an OR filter. See documentation for supported country codes.
          example:
          - ''
          items:
            type: string
        excludeCountry:
          type:
          - array
          - 'null'
          description: Exclude articles from specific countries using two-letter country codes in lowercase. Accepts either a single country code or an array. Multiple values create an AND-exclude filter. See documentation for supported country codes.
          example:
          - ''
          items:
            type: string
        locationsCountry:
          type:
          - array
          - 'null'
          description: Filter articles where specified countries play a central role in the content, not just mentioned. Uses two-letter country codes in lowercase. Accepts either a single country code or an array. Multiple values create an OR filter. See documentation for supported country codes.
          example:
          - ''
          items:
            type: string
        excludeLocationsCountry:
          type:
          - array
          - 'null'
          description: Exclude articles where specified countries play a central role in the content. Accepts either a single country code or an array. Multiple values create an AND-exclude filter, removing articles focused on any of these countries. See documentation for supported country codes.
          example:
          - ''
          items:
            type: string
        state:
          type:
          - array
          - 'null'
          description: Filter articles where specified states play a central role in the content. Accepts either a single state code or an array. Multiple values create an OR filter. Uses two-letter state codes in lowercase. See documentation for supported state codes.
          example:
          - ''
          items:
            type: string
        excludeState:
          type:
          - array
          - 'null'
          description: Exclude articles where specified states play a central role. Accepts either a single state code or an array. Multiple values create an AND-exclude filter, removing articles focused on any of these states. See documentation for supported state codes.
          example:
          - ''
          items:
            type: string
        county:
          type:
          - array
          - 'null'
          description: Filter articles that mention or are related to specific counties. Accepts either a single county name or an array. Multiple values create an OR filter. County names typically include the word 'County' (e.g., Los Angeles County).
          example:
          - ''
          items:
            type: string
        excludeCounty:
          type:
          - array
          - 'null'
          description: Exclude articles that mention or are related to specific counties. Accepts either a single county name or an array. Multiple values create an AND-exclude filter. County names should match the format in article metadata (e.g., Los Angeles County, Cook County).
          example:
          - ''
          items:
            type: string
        city:
          type:
          - array
          - 'null'
          description: Filter articles that mention or are related to specific cities. Accepts either a single city name or an array. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        excludeCity:
          type:
          - array
          - 'null'
          description: Exclude articles that mention or are related to specific cities. Accepts either a single city name or an array. Multiple values create an AND-exclude filter.
          example:
          - ''
          items:
            type: string
        sourceCountry:
          type:
          - array
          - 'null'
          description: Filter for articles from publishers based in specific countries. Accepts either a single country code or an array. Uses two-letter country codes in lowercase (e.g., us, gb). See documentation for supported country codes.
          example:
          - ''
          items:
            type: string
        sourceState:
          type:
          - array
          - 'null'
          description: Filter for articles from publishers based in specific states or regions. Accepts either a single state code or an array. Uses two-letter state codes in lowercase. See documentation for supported state codes.
          example:
          - ''
          items:
            type: string
        sourceCounty:
          type:
          - array
          - 'null'
          description: Filter for articles from publishers based in specific counties. Accepts either a single county name or an array. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        sourceCity:
          type:
          - array
          - 'null'
          description: Filter for articles from publishers based in specific cities. Accepts either a single city name or an array. Multiple values create an OR filter.
          example:
          - ''
          items:
            type: string
        coordinates:
          allOf:
          - $ref: '#/components/schemas/CoordinateFilter'
        sourceCoordinates:
          allOf:
          - $ref: '#/components/schemas/CoordinateFilter'
        companyId:
          type:
          - array
          - 'null'
          description: Filter articles by company identifiers. Accepts either a single ID or an array. Multiple values create an OR filter. For a complete list of tracked companies and their IDs, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        excludeCompanyId:
          type:
          - array
          - 'null'
          description: Exclude articles mentioning companies with specific identifiers. Accepts either a single ID or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their IDs, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        companyDomain:
          type:
          - array
          - 'null'
          description: Filter articles by company domains (e.g., apple.com). Accepts either a single domain or an array. Multiple values create an OR filter. For a complete list of tracked companies and their domains, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        excludeCompanyDomain:
          type:
          - array
          - 'null'
          description: Exclude articles related to companies with specific domains. Accepts either a single domain or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their domains, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        companySymbol:
          type:
          - array
          - 'null'
          description: Filter articles by company stock symbols (e.g., AAPL, MSFT). Accepts either a single symbol or an array. Multiple values create an OR filter. For a complete list of tracked companies and their symbols, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        excludeCompanySymbol:
          type:
          - array
          - 'null'
          description: Exclude articles related to companies with specific stock symbols. Accepts either a single symbol or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their symbols, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        companyName:
          type:
          - array
          - 'null'
          description: Filter articles by company name mentions. Accepts either a single name or an array. Performs exact matching on company names. Multiple values create an OR filter. For a complete list of tracked companies and their names, refer to the /companies endpoint.
          example:
          - ''
          items:
            type: string
        personWikidataId:
          type:
          - array
          - 'null'
          description: Filter articles by Wikidata IDs of mentioned people. Accepts either a single ID or an array. Multiple values create an OR filter. For a complete list of tracked individuals and their Wikidata IDs, refer to the /people endpoint.
          example:
          - ''
          items:
            type: string
        excludePersonWikidataId:
          type:
          - array
          - 'null'
          description: Exclude articles mentioning people with specific Wikidata IDs. Accepts either a single ID or an array. Multiple values create an AND-exclude filter. For a complete list of tracked individuals and their Wikidata IDs, refer to the /people endpoint.
          example:
          - ''
          items:
            type: string
        personName:
          type:
          - array
          - 'null'
          description: Filter articles by exact person name matches. Accepts either a single name or an array. Does not support Boolean operators or wildcards. Multiple values create an OR filter. For a complete list of tracked individuals and their names, refer to the /people endpoint.
          example:
          - ''
          items:
            type: string
        excludePersonName:
          type:
          - array
          - 'null'
          description: Exclude articles mentioning specific people by name. Accepts either a single name or an array. Multiple values create an AND-exclude filter. For a complete list of tracked individuals and their names, refer to the /people endpoint.
          example:
          - ''
          items:
            type: string
        AND:
          type:
          - array
          - 'null'
          description: Adds additional AND filter objects. These objects must be of the same type as the original filter object and will be combined with the existing filter using the AND logical operator.
          example:
          - {}
          items:
            $ref: '#/components/schemas/ArticleSearchFilter'
        OR:
          type:
          - array
          - 'null'
          description: Adds additional OR filter objects. These objects must be of the same type as the original filter object and will be combined with the existing filter using the OR logical operator.
          example:
          - {}
          items:
            $ref: '#/components/schemas/ArticleSearchFilter'
        NOT:
          type:
          - array
          - 'null'
          description: A filter object for logical NOT operations
          example:
          - {}
          items:
            $ref: '#/components/schemas/ArticleSearchFilter'
      description: Complex filter structure for article searches that supports nested logical operations (AND, OR, NOT) and multiple filtering criteria.
    NewsCluster:
      type: object
      properties:
        createdAt:
          type:
          - string
          - 'null'
          description: Date and time the story was created, in ISO 8601 format.
        updatedAt:
          type:
          - string
          - 'null'
          description: Date and time the story was last updated, in ISO 8601 format.
        initializedAt:
          type:
          - string
          - 'null'
          description: Date and time the story became initialized and visible, in ISO 8601 format.
        id:
          type:
          - string
          - 'null'
          description: Unique identifier for the story cluster.
        duplicateOf:
          type:
          - string
          - 'null'
          description: Identifier of the original story when this story is a duplicate.
        slug:
          type:
          - string
          - 'null'
          description: URL-safe identifier for the story.
        name:
          type:
          - string
          - 'null'
          description: Generated story title.
        summary:
          type:
          - string
          - 'null'
          description: Generated story summary.
        shortSummary:
          type:
          - string
          - 'null'
          description: Short generated story summary, when available.
        summaryReferences:
          type:
          - array
          - 'null'
          description: Article IDs supporting the story summary.
          items:
            type: string
            description: Article IDs supporting the story summary.
        imageSource:
          allOf:
          - $ref: '#/components/schemas/SourceHolder'
        imageUrl:
          type:
          - string
          - 'null'
          description: Primary image URL selected for the story.
        keyPoints:
          type:
          - array
          - 'null'
          description: Key facts and developments identified in the story.
          items:
            $ref: '#/components/schemas/KeyPoint'
        questions:
          type:
          - array
          - 'null'
          description: Questions and answers generated from the story content.
          items:
            $ref: '#/components/schemas/Question'
        uniqueSources:
          type:
          - array
          - 'null'
          description: Distinct publisher domains represented in the story.
          items:
            type: string
            description: Distinct publisher domains represented in the story.
        selectedArticles:
          type:
          - array
          - 'null'
          description: Representative articles selected for the story.
          items:
            $ref: '#/components/schemas/Article'
        sentiment:
          allOf:
          - $ref: '#/components/schemas/SentimentHolder'
        uniqueCount:
          type:
          - integer
          - 'null'
          description: Number of unique articles in the story.
          format: int32
        reprintCount:
          type:
          - integer
          - 'null'
          description: Number of reprinted articles in the story.
          format: int32
        totalCount:
          type:
          - integer
          - 'null'
          description: Total article count including reprints.
          format: int32
        countries:
          type:
          - array
          - 'null'
          description: Countries associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/RecordStatHolder'
        topCountries:
          type:
          - array
          - 'null'
          description: Countries most strongly associated with the story.
          items:
            type: string
            description: Countries most strongly associated with the story.
        topics:
          type:
          - array
          - 'null'
          description: Topics associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/RecordStatHolder'
        topTopics:
          type:
          - array
          - 'null'
          description: Topics most strongly associated with the story.
          items:
            $ref: '#/components/schemas/TopicHolder'
        categories:
          type:
          - array
          - 'null'
          description: Categories associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/RecordStatHolder'
        topCategories:
          type:
          - array
          - 'null'
          description: Categories most strongly associated with the story.
          items:
            $ref: '#/components/schemas/CategoryHolder'
        taxonomies:
          type:
          - array
          - 'null'
          description: Google Content Categories associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/RecordStatHolder'
        topTaxonomies:
          type:
          - array
          - 'null'
          description: Google Content Categories most strongly associated with the story.
          items:
            $ref: '#/components/schemas/CategoryHolder'
        people:
          type:
          - array
          - 'null'
          description: People associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/PersonCount'
        topPeople:
          type:
          - array
          - 'null'
          description: People most strongly associated with the story.
          items:
            $ref: '#/components/schemas/PersonHolder'
        companies:
          type:
          - array
          - 'null'
          description: Companies associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/CompanyCount'
        topCompanies:
          type:
          - array
          - 'null'
          description: Companies most strongly associated with the story.
          items:
            $ref: '#/components/schemas/CompanyHolder'
        locations:
          type:
          - array
          - 'null'
          description: Locations associated with the story and their article counts.
          items:
            $ref: '#/components/schemas/LocationCount'
        topLocations:
          type:
          - array
          - 'null'
          description: Locations most strongly associated with the story.
          items:
            $ref: '#/components/schemas/LocationHolder'
        highlights:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            description: Matched text fragments grouped by story field.
            items:
              type: string
              description: Matched text fragments grouped by story field.
          description: Matched text fragments grouped by story field.
        sourceDiversity:
          type:
          - number
          - 'null'
          description: Ratio of unique publisher domains to total articles in the story.
          format: double
      description: Expanded story cluster details, when requested and available.
    SourceLocation:
      type: object
      properties:
        country:
          type:
          - string
          - 'null'
          description: Country where the publisher is located.
        state:
          type:
          - string
          - 'null'
          description: State or region where the publisher is located.
        county:
          type:
          - string
          - 'null'
          description: County where the publisher is located.
        city:
          type:
          - string
          - 'null'
          description: City where the publisher is located.
        coordinates:
          allOf:
          - $ref: '#/components/schemas/Coordinate'
      description: Geographic location of the publisher, when available.
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          format: int32
        message:
          type:
          - string
          - 'null'
        timestamp:
          type:
          - integer
          - 'null'
          format: int64
    PersonHolder:
      type: object
      properties:
        wikidataId:
          type:
          - string
          - 'null'
          description: Wikidata identifier for the person.
        name:
          type:
          - string
          - 'null'
          description: Person name.
      description: People most strongly associated with the story.
    AllEndpointSortBy:
      type: string
      enum:
      - relevance
      - date
      - reverseDate
      - reverseAddDate
      - addDate
      - pubDate
      - refreshDate
    CoordinateFilter:
      type: object
      properties:
        lat:
          type:
          - number
          - 'null'
          format: float
          example: 0
        lon:
          type:
          - number
          - 'null'
          format: float
          example: 0
        radius:
          type:
          - number
          - 'null'
          format: float
          example: 0
      description: Filter articles from publishers based at specific geographic locations. Uses latitude, longitude, and radius parameters to define a circular search area for publisher locations.
    ArticleRefreshPeekResponse:
      type: object
      properties:
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ArticleRefreshPeekResult'
    PersonCount:
      type: object
      properties:
        wikidataId:
          type:
          - string
          - 'null'
          description: Wikidata identifier for the person.
        name:
          type:
          - string
          - 'null'
          description: Person name.
        count:
          type:
          - integer
          - 'null'
          description: Number of story articles mentioning the person.
          format: int32
      description: People associated with the story and their article counts.
    CompanyCount:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique Perigon identifier for the company.
        name:
          type:
          - string
          - 'null'
          description: Company name.
        domains:
          type:
          - array
          - 'null'
          description: Domains associated with the company.
          items:
            type: string
            description: Domains associated with the company.
        symbols:
          type:
          - array
          - 'null'
          description: Stock symbols associated with the company.
          items:
            type: string
            description: Stock symbols associated with the company.
        count:
          type:
          - integer
          - 'null'
          description: Number of story articles mentioning the company.
          format: int32
      description: Companies associated with the story and their article counts.
    ArticleRefreshPeekResult:
      type: object
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/ArticleRefreshData'
        fetchedAt:
          type:
          - string
          - 'null'
          format: date-time
        validatedAt:
          type:
          - string
          - 'null'
          format: date-time
    StoryHistoryResult:
      required:
      - numResults
      - results
      - status
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code for the response.
          format: int32
        numResults:
          type: integer
          description: Total number of matching history records.
          format: int64
        results:
          type: array
          description: History records returned for the requested page.
          items:
            $ref: '#/components/schemas/StoryHistoryRecord'
      description: Story history result
      example:
        status: 200
        numResults: 4530319
        results:
        - clusterId: 911860d569ca464698c0beec0697f694
          createdAt: '2025-08-12T10:18:48.493128+00:00'
          name: null
          triggeredAt: '2025-08-12T10:17:41.249815+00:00'
          summary: The Indian stock market experienced notable volatility and ended lower on August 12, with the Sensex dropping 368.49 points to 80,235.59 and the Nifty falling 97.65 points to 24,487.40, reversing early gains amid cautious investor sentiment ahead of key inflation data from India and the US. Financial and private banking sectors faced selling pressure, while auto, IT, and media sectors showed gains, supported by strong performances in large-cap stocks like Maruti Suzuki and Tech Mahindra. Market experts warned of potential overheating in the rally, especially in mid and small caps, urging investors to remain selective due to short-term uncertainties despite favorable long-term prospects. The broader market showed mixed movements, with smallcaps outperforming midcaps and a slight easing in market volatility as gauged by India VIX. Investors remained watchful of the July retail inflation print, expected to dip to a historic low of 1.4%, and global concerns over US tariffs adding to price pressures. Overall, the market's cautious stance reflects anticipation around inflation data and geopolitical events, including the Trump-Putin summit, amid mixed sector performances and ongoing foreign selling pressure.
          shortSummary: Indian equity markets showed volatility with the Sensex and Nifty reversing early gains to close lower amid cautious investor sentiment ahead of key inflation data from India and the US. Financial and private banking sectors faced selling pressure while auto, IT, and media sectors outperformed, with mixed performances in mid and small caps as investors weigh global events including US tariffs and mutual fund inflows.
          changelog: null
          keyPoints:
          - point: The IPO of Bluestone Jewelry and Lifestyle Limited (BJLL) opened on August 11, aiming to raise ₹1,540.65 crore, with listing scheduled for August 19 on BSE and NSE.
            references:
            - 574436fd177e4af5a166a439a5bc97a0
          - point: Among the Sensex components, 17 shares settled in the red, with notable losers including Bajaj Finance, HUL, Trent, HDFC Bank, ICICI Bank, Kotak Bank, BEL, Bajaj Finserv, Adani Ports, and Asian Paints.
            references:
            - 574436fd177e4af5a166a439a5bc97a0
          - point: Market breadth showed about 1,994 shares advanced, 1,889 declined, and 157 remained unchanged, indicating a mixed but slightly positive broader market.
            references:
            - 184a5f45336e4129b4e220d901abef10
          - point: SBI report highlighted expectations that CPI inflation in India will remain below 3 percent until the third quarter of FY26, contributing to market volatility and cautious investor sentiment.
            references:
            - bed7d190e0b64f17aa1f77012bf634af
          - point: Several stocks hit new 52-week highs and lows, with 23 stocks including Star Cement and Anand Rathi reaching 52-week highs, while 45 stocks including Bigbloc Construction and Praj Industries hit 52-week lows, reflecting uneven market performance.
            references:
            - bed7d190e0b64f17aa1f77012bf634af
          questions: null
    ArticleRefreshJobArticleResult:
      type: object
      properties:
        articleId:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
          enum:
          - PENDING
          - COMPLETED
          - ERROR
        data:
          allOf:
          - $ref: '#/components/schemas/ArticleRefreshData'
        computedAt:
          type:
          - string
          - 'null'
          format: date-time
    KeywordHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Keyword extracted from the article.
        weight:
          type:
          - number
          - 'null'
          description: Relative relevance weight of the keyword.
          format: float
      description: Keywords extracted from the article with their relevance weights.
    SourceHolder:
      type: object
      properties:
        domain:
          type:
          - string
          - 'null'
          description: Publisher domain.
        paywall:
          type:
          - boolean
          - 'null'
          description: Whether the publisher uses a paywall, when known.
        location:
          allOf:
          - $ref: '#/components/schemas/SourceLocation'
      description: Publisher information for the selected story image.
    ArticleSearchParams:
      required:
      - prompt
      type: object
      properties:
        prompt:
          maxLength: 1024
          minLength: 0
          type: string
          description: Natural language query to search the news articles database
          example: Enter your prompt
        filter:
          allOf:
          - $ref: '#/components/schemas/ArticleSearchFilter'
        pubDateFrom:
          type:
          - string
          - 'null'
          description: '''pubDateFrom'' filter, will search articles published after the specified date, the date could be passed as ISO or ''yyyy-mm-dd''. Date time in ISO format, ie. 2024-01-01T00:00:00 - Default: Only articles with a pubDate within the last 30 days of the request'
          format: date-time
          example: '2024-01-01T00:00:00Z'
        pubDateTo:
          type:
          - string
          - 'null'
          description: '''pubDateTo'' filter, will search articles published before the specified date, the date could be passed as ISO or ''yyyy-mm-dd''. Date time in ISO format, ie. 2024-01-01T00:00:00'
          format: date-time
          example: '2024-12-31T23:59:59Z'
        showReprints:
          type:
          - boolean
          - 'null'
          description: Whether to return reprints in the response or not. Reprints are usually wired articles from sources like AP or Reuters that are reprinted in multiple sources at the same time. By default, this parameter is 'true'.
          default: true
        size:
          maximum: 100
          minimum: 1
          type:
          - integer
          - 'null'
          description: The number of items per page.
          format: int32
          default: 10
        page:
          maximum: 10000
          minimum: 0
          type:
          - integer
          - 'null'
          description: The page number to retrieve.
          format: int32
          default: 0
    VectorData:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          description: Numeric values in the vector embedding.
          items:
            type: number
            description: Numeric values in the vector embedding.
            format: float
        version:
          type:
          - integer
          - 'null'
          description: Version of the embedding representation.
          format: int32
      description: Vector embeddings associated with the article, when requested.
    IdNameHolder:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier for the matched record.
        name:
          type:
          - string
          - 'null'
          description: Display name of the matched record.
      description: Known journalist records matched to the article byline.
    ArticleRefreshData:
      type: object
      properties:
        articleId:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        authorsByline:
          type:
          - string
          - 'null'
        imageUrl:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        language:
          type:
          - string
          - 'null'
        pubDate:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        content:
          type:
          - string
          - 'null'
        source:
          allOf:
          - $ref: '#/components/schemas/SourceHolder'
        links:
          type:
          - array
          - 'null'
          items:
            type: string
        medium:
          type:
          - string
          - 'null'
        claim:
          type:
          - string
          - 'null'
        verdict:
          type:
          - string
          - 'null'
        translation:
          type:
          - string
          - 'null'
        translatedTitle:
          type:
          - string
          - 'null'
        translatedDescription:
          type:
          - string
          - 'null'
        entities:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EntityHolder'
        people:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PersonHolder'
        companies:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CompanyHolder'
        matchedAuthors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IdNameHolder'
    Question:
      type: object
      properties:
        question:
          type:
          - string
          - 'null'
          description: Question generated from the story content.
        answer:
          type:
          - string
          - 'null'
          description: Answer generated from the story content.
        references:
          type:
          - array
          - 'null'
          description: Article IDs supporting the answer.
          items:
            type: string
            description: Article IDs supporting the answer.
      description: Questions and answers generated from the story content.
    LocationHolder:
      type: object
      properties:
        country:
          type:
          - string
          - 'null'
          description: Country central to the article.
        state:
          type:
          - string
          - 'null'
          description: State or region central to the article.
        county:
          type:
          - string
          - 'null'
          description: County central to the article.
        city:
          type:
          - string
          - 'null'
          description: City central to the article.
        area:
          type:
          - string
          - 'null'
          description: Neighborhood, borough, or district central to the article.
      description: Locations most strongly associated with the story.
    RecordStatHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the aggregated value.
        count:
          type:
          - integer
          - 'null'
          description: Number of matching articles for the value.
          format: int32
      description: Google Content Categories associated with the story and their article counts.
    NameCount:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the aggregated value.
        count:
          type:
          - integer
          - 'null'
          description: Number of matching records for the value.
          format: int64
      description: Countries most frequently associated with the journalist's articles.
    TopicHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Topic assigned to the article.
      description: Topics most strongly associated with the story.
    StatResult:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code for the response.
          format: int32
        results:
          type:
          - array
          - 'null'
          description: Statistics returned by the request.
          items:
            type: object
            description: Statistics returned by the request.
        numResults:
          type:
          - integer
          - 'null'
          description: Total number of matching records, when calculated by the endpoint.
          format: int64
    StoryHistoryRecord:
      type: object
      properties:
        clusterId:
          type:
          - string
          - 'null'
          description: Unique identifier of the story associated with this history record.
        createdAt:
          type:
          - string
          - 'null'
          description: Date and time the history record was created, in ISO 8601 format.
        name:
          type:
          - string
          - 'null'
          description: Story name captured in this history record, when available.
        triggeredAt:
          type:
          - string
          - 'null'
          description: Date and time the story refresh that produced this record was triggered, in ISO 8601 format.
        summary:
          type:
          - string
          - 'null'
          description: Story summary captured in this history record.
        shortSummary:
          type:
          - string
          - 'null'
          description: Short story summary captured in this history record, when available.
        changelog:
          type:
          - string
          - 'null'
          description: Description of changes from the previous story version, when available.
        keyPoints:
          type:
          - array
          - 'null'
          description: Key points captured for this version of the story.
          items:
            $ref: '#/components/schemas/KeyPoint'
        questions:
          type:
          - array
          - 'null'
          description: Questions and answers generated for this version of the story.
          items:
            $ref: '#/components/schemas/Question'
      description: History records returned for the requested page.
    LocationCount:
      type: object
      properties:
        country:
          type:
          - string
          - 'null'
          description: Country associated with the story.
        state:
          type:
          - string
          - 'null'
          description: State or region associated with the story.
        county:
          type:
          - string
          - 'null'
          description: County associated with the story.
        city:
          type:
          - string
          - 'null'
          description: City associated with the story.
        area:
          type:
          - string
          - 'null'
          description: Neighborhood, borough, or district associated with the story.
        count:
          type:
          - integer
          - 'null'
          description: Number of story articles associated with the location.
          format: int32
      description: Locations associated with the story and their article counts.
    ScoredDataArticle:
      type: object
      properties:
        score:
          type:
          - number
          - 'null'
          format: float
        data:
          allOf:
          - $ref: '#/components/schemas/Article'
        vectors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/VectorData'
    CompanyHolder:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique Perigon identifier for the company.
        name:
          type:
          - string
          - 'null'
          description: Company name.
        domains:
          type:
          - array
          - 'null'
          description: Domains associated with the company.
          items:
            type: string
            description: Domains associated with the company.
        symbols:
          type:
          - array
          - 'null'
          description: Stock symbols associated with the company.
          items:
            type: string
            description: Stock symbols associated with the company.
      description: Companies most strongly associated with the story.
    ClustersListSortBy:
      type: string
      enum:
      - createdAt
      - updatedAt
      - relevance
      - count
      - totalCount
    CategoryHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Content category assigned to the article.
      description: Google Content Categories most strongly associated with the story.
    ArticleRefreshSubmitRequest:
      required:
      - articleIds
      type: object
      properties:
        articleIds:
          maxItems: 100
          minItems: 0
          type: array
          items:
            type: string
    Journalist:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique Perigon identifier for the journalist.
        primaryRecordId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
          description: Common display name of the journalist.
        fullName:
          type:
          - string
          - 'null'
          description: Full name of the journalist.
        headline:
          type:
          - string
          - 'null'
          description: Professional headline associated with the journalist.
        description:
          type:
          - string
          - 'null'
          description: Biographical description of the journalist.
        title:
          type:
          - string
          - 'null'
          description: Professional title of the journalist.
        email:
          type:
          - string
          - 'null'
          description: Journalist's email.
        locations:
          type:
          - array
          - 'null'
          description: Locations associated with the journalist.
          items:
            $ref: '#/components/schemas/LocationHolder'
        updatedAt:
          type:
          - string
          - 'null'
          description: Date and time the journalist record was last refreshed, in ISO 8601 format.
        topTopics:
          type:
          - array
          - 'null'
          description: Topics most frequently covered by the journalist.
          items:
            $ref: '#/components/schemas/NameCount'
        topSources:
          type:
          - array
          - 'null'
          description: Publishers most frequently associated with the journalist.
          items:
            $ref: '#/components/schemas/NameCount'
        topCategories:
          type:
          - array
          - 'null'
          description: Categories most frequently covered by the journalist.
          items:
            $ref: '#/components/schemas/NameCount'
        topLabels:
          type:
          - array
          - 'null'
          description: Editorial labels most frequently associated with the journalist's articles.
          items:
            $ref: '#/components/schemas/NameCount'
        topCountries:
          type:
          - array
          - 'null'
          description: Countries most frequently associated with the journalist's articles.
          items:
            $ref: '#/components/schemas/NameCount'
        avgMonthlyPosts:
          type:
          - integer
          - 'null'
          description: Average number of articles published by the journalist per month.
          format: int32
        twitterHandle:
          type:
          - string
          - 'null'
          description: Journalist's X or Twitter handle.
        twitterBio:
          type:
          - string
          - 'null'
          description: Biography from the journalist's X or Twitter profile.
        imageUrl:
          type:
          - string
          - 'null'
          description: Profile image URL for the journalist.
        linkedinUrl:
          type:
          - string
          - 'null'
          description: LinkedIn profile URL for the journalist.
        linkedinConnections:
          type:
          - integer
          - 'null'
          description: LinkedIn connection count for the journalist, when available.
          format: int32
        linkedinFollowers:
          type:
          - integer
          - 'null'
          description: LinkedIn follower count for the journalist, when available.
          format: int32
        facebookUrl:
          type:
          - string
          - 'null'
          description: Facebook profile URL for the journalist.
        instagramUrl:
          type:
          - string
          - 'null'
          description: Instagram profile URL for the journalist.
        websiteUrl:
          type:
          - string
          - 'null'
          description: Personal or professional website URL for the journalist.
        blogUrl:
          type:
          - string
          - 'null'
          description: Blog URL for the journalist.
        tumblrUrl:
          type:
          - string
          - 'null'
          description: Tumblr profile URL for the journalist.
        youtubeUrl:
          type:
          - string
          - 'null'
          description: YouTube channel URL for the journalist.
      description: Expanded journalist details, when requested and available.
    SentimentHolder:
      type: object
      properties:
        positive:
          type:
          - number
          - 'null'
          description: Positive sentiment score from 0 to 1.
          format: float
        negative:
          type:
          - number
          - 'null'
          description: Negative sentiment score from 0 to 1.
          format: float
        neutral:
          type:
          - number
          - 'null'
          description: Neutral sentiment score from 0 to 1.
          format: float
      description: Aggregate sentiment scores for the story.
    ArticlesVectorSearchResult:
      required:
      - results
      - status
      type: object
      properties:
        status:
          type: integer
          format: int32
        results:
          type: array
          items:
            $ref: '#/components/schemas/ScoredDataArticle'
      description: Articles vector search result
      example:
        status: 200
        results:
        - score: 0.6707077
          data:
            articleId: be5db1909bb94e0e953c0537d80d1728
            clusterId: 85246d2dfb784a66a70946c382000615
            url: https://woai.iheart.com/content/2025-07-30-tesla-samsung-select-texas-town-as-new-hub-for-ai-chip-manufacturing/
            authorsByline: ''
            matchedAuthors: []
            imageUrl: https://i.iheart.com/v3/re/assets.getty/64d0f5da53634efa19c55bbb?ops=gravity(%22north%22),fit(1200,675),quality(65)
            pubDate: '2025-07-31T08:30:00Z'
            addDate: '2025-07-31T08:37:17.593902Z'
            language: en
            source:
              domain: woai.iheart.com
              location:
                country: us
                state: AZ
                county: Pima County
                city: Tucson
                coordinates:
                  lat: 32.1988848
                  lon: -110.8218543
            country: us
            reprint: false
            reprintGroupId: ab5901166eff4e8781ad9bf362818ed6
            title: Tesla, Samsung Select Texas Town As New Hub For AI Chip Manufacturing
            translatedTitle: ''
            summary: Texas has seen significant growth in recent years, largely due to companies like Tesla and Samsung moving operations to the state. This comes as Tesla signed a $16.5 billion deal with Samsung to manufacture new AI6 chips in Taylor, Texas. The chips are considered the brains behind Tesla's next-generation autonomous vehicles. This investment in Texas is seen as a significant investment that will keep a significant amount of money and jobs in the state, particularly as AI continues to grow. The deal signals that Texas is now the leading for technology, outpacing Silicon Valley. This is also a sign that the state is becoming more relevant in the rapidly changing world of technological advancement.
            translatedSummary: ''
            labels: []
            topics:
            - name: AI
            taxonomies:
            - name: /News/Technology News
            - name: /News/Business News/Company News
            - name: /Autos & Vehicles/Motor Vehicles (By Brand)/Tesla Motors
            categories:
            - name: Tech
            - name: Auto
            entities:
            - data: Tesla
              type: ORG
              mentions: 4
            - data: Samsung
              type: ORG
              mentions: 2
            - data: KTRH High Tech
              type: ORG
              mentions: 1
            - data: Texas
              type: GPE
              mentions: 11
            - data: the Lone Star State
              type: GPE
              mentions: 2
            - data: Taylor
              type: GPE
              mentions: 1
            - data: South Korea
              type: GPE
              mentions: 1
            - data: Taiwan
              type: GPE
              mentions: 1
            - data: AI6
              type: PRODUCT
              mentions: 1
            - data: Texans
              type: NORP
              mentions: 1
            - data: American
              type: NORP
              mentions: 1
            - data: Michael Garfield
              type: PERSON
              mentions: 3
            - data: Trump
              type: PERSON
              mentions: 1
            - data: Silicon Valley
              type: LOC
              mentions: 1
            companies:
            - id: 16c0e6ea111945fb9c5af03fc7ce6d82
              name: Samsung C&T Corporation
              domains:
              - samsungcnt.com
              symbols:
              - 028260.KS
              - 02826K.KS
            - id: 165c2312f79e4d3d982a75eec3054904
              name: Samsung India Software Operations
              domains:
              - samsungindiasoft.com
              symbols: []
            - id: eeee660a046242b8bf99f45fdc95cc32
              name: Tesla, Inc.
              domains:
              - tesla.com
              symbols:
              - TSLA
              - TL0.DE
            people: []
            locations:
            - country: us
              state: TX
              county: Williamson County
            places: []
    QuerySearchResult:
      required:
      - articles
      - numResults
      - status
      type: object
      properties:
        status:
          type: integer
          format: int32
        numResults:
          type: integer
          format: int64
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
      example:
        status: 200
        numResults: 10000
        articles:
        - url: https://www.breitbart.com/news/south-koreas-lee-trump-to-hold-summit-at-white-house-on-aug-25/
          authorsByline: UPI
          articleId: 97dce2f1bdcd441c99360e58d38e811d
          clusterId: 87f8c1cdc02f41e0b6fc818f86239c7f
          source:
            domain: breitbart.com
            paywall: false
            location: null
          imageUrl: https://media.breitbart.com/media/2025/08/wi/upi/south-koreas-lee-trump-hold-summit-at-white-house-aug-25-south-korea-lee-trump-hold-summit-at-white.jpg
          country: us
          language: en
          pubDate: '2025-08-12T02:40:08+00:00'
          addDate: '2025-08-12T09:50:33.647613+00:00'
          refreshDate: '2025-08-12T09:50:33.647614+00:00'
          score: 1.0
          title: South Korea's Lee, Trump to hold summit at White House on Aug. 25
          description: SEOUL, Aug. 12 (UPI) -- South Korean President Lee Jae Myung will travel to Washington to hold a summit with U.S. President Donald Trump on Aug. 25, Lee's
          content: 'SEOUL, Aug. 12 (UPI) — South Korean President Lee Jae Myung will travel to Washington to hold a summit with U.S. President Donald Trump on Aug. 25, Lee’s office said Tuesday, with trade and defense issues expected to be at the top of the agenda.


            The three-day visit will be Lee’s first trip to the United States since taking office in June, presidential spokeswoman Kang Yu-jung said at a press briefing.


            “The two leaders plan to discuss ways to develop the Korea-U.S. alliance into a future comprehensive strategic alliance in response to the changing international security and economic environment,” Kang said.


            “They will also discuss ways to further strengthen the robust South Korea-U.S. combined defense posture and to cooperate to establish peace and achieve denuclearization on the Korean Peninsula,” she added.


            The summit comes weeks after Seoul and Washington struck a trade deal that lowered Trump’s threatened 25% tariffs on South Korean goods to 15%. As part of the package, South Korea pledged to invest $350 billion in the United States and to purchase $100 billion in U.S. energy.


            Based on the tariff deal, Trump and Lee will consult on economic cooperation in semiconductors, batteries and shipbuilding, as well as partnerships in advanced technologies and key minerals, Kang said.


            The future of the decades-old South Korea-U.S. military alliance is also expected to be in the spotlight as the two countries prepare to kick off their annual Ulchi Freedom Shield joint exercise on Monday.


            During his previous term in office, Trump called for massive increases in Seoul’s financial contribution for the 28,500 U.S. forces stationed in Korea.


            Seoul signed a new five-year cost-sharing agreement with Washington in October, but Trump has suggested he would look to renegotiate the terms of the deal amid calls for allies to increase their defense spending.


            “South Korea is making a lot of money, and they’re very good,” Trump told reporters at a Cabinet meeting in the White House last month. “They’re very good, but, you know, they should be paying for their own military.”


            On Friday, Gen. Xavier Brunson, commander of U.S. Forces Korea, discussed the need to restructure the military alliance in response to an evolving regional security environment.


            “Alliance modernization … reflects the recognition that the world’s changed around us,” Brunson told local reporters at a press briefing in Pyeongtaek. “We have a nuclear-armed adversary who’s north of the border. We have increasing involvement of Russia, along with the DPRK, and we also have the Chinese and the threat that they pose to a free and open Indo-Pacific.”


            The Democratic People’s Republic of Korea is the official name of North Korea.


            Brunson avoided the question of a potential of U.S. troop reduction on the peninsula, stressing military capabilities and strategic flexibility over numbers ahead of the Lee-Trump summit.


            “We’re going to have two chief executives sitting down together to discuss not only the security situation in the region, but the security situation in the world,” he said. “For us, it’s about the capabilities. We want to have the right capabilities resident on the Peninsula.”


            Lee will be in the United States from Aug. 24-26 for his summit with Trump. In response to local media reports that Lee may also stop in Japan around the time of his U.S. trip, presidential spokeswoman Kang said that nothing had been confirmed.'
          medium: Article
          links: []
          labels: []
          matchedAuthors: []
          claim: ''
          verdict: ''
          keywords:
          - name: U.S. Forces Korea
            weight: 0.09803479
          - name: U.S. President Donald Trump
            weight: 0.09388354
          - name: South Korea
            weight: 0.08868486
          - name: U.S.
            weight: 0.077976175
          - name: North Korea
            weight: 0.077027455
          - name: U.S. troop reduction
            weight: 0.07701537
          - name: Korea
            weight: 0.076576516
          - name: U.S. energy
            weight: 0.0765642
          - name: Donald Trump
            weight: 0.07466888
          - name: Trump
            weight: 0.07382798
          topics: []
          categories:
          - name: Politics
          taxonomies:
          - name: /News/Politics/Other
            score: 0.98291015625
          - name: /Law & Government/Government/Executive Branch
            score: 0.96337890625
          - name: /People & Society/Social Sciences/Political Science
            score: 0.8974609375
          entities:
          - data: South Korea's
            type: GPE
            mentions: 7
          - data: SEOUL
            type: GPE
            mentions: 1
          - data: Washington
            type: GPE
            mentions: 3
          - data: U.S.
            type: GPE
            mentions: 7
          - data: the United States
            type: GPE
            mentions: 3
          - data: Seoul
            type: GPE
            mentions: 3
          - data: Pyeongtaek
            type: GPE
            mentions: 1
          - data: Russia
            type: GPE
            mentions: 1
          - data: DPRK
            type: GPE
            mentions: 1
          - data: The Democratic People’s Republic of Korea
            type: GPE
            mentions: 2
          - data: Japan
            type: GPE
            mentions: 1
          - data: Lee
            type: PERSON
            mentions: 8
          - data: Trump
            type: PERSON
            mentions: 8
          - data: Kang Yu-jung
            type: PERSON
            mentions: 4
          - data: Xavier Brunson
            type: PERSON
            mentions: 3
          - data: White House
            type: ORG
            mentions: 1
          - data: Cabinet
            type: ORG
            mentions: 1
          - data: U.S. Forces Korea
            type: ORG
            mentions: 1
          - data: South Korean
            type: NORP
            mentions: 2
          - data: Chinese
            type: NORP
            mentions: 1
          - data: the Korean Peninsula
            type: LOC
            mentions: 2
          - data: Indo
            type: LOC
            mentions: 1
          - data: '-'
            type: LOC
            mentions: 1
          - data: Pacific
            type: LOC
            mentions: 1
          - data: Ulchi Freedom Shield
            type: PRODUCT
            mentions: 1
          - data: the White House
            type: FAC
            mentions: 1
          companies: []
          sentiment:
            positive: 0.655995
            negative: 0.103086375
            neutral: 0.24091867
          summary: South Korean President Lee Jae Myung is set to meet with U.S. President Donald Trump on Aug. 25, this will be his first trip to the United States since taking office in June. The summit will focus on trade and defense issues, with the two leaders expected to discuss ways to develop the Korea-U.S.-Korea alliance into a future comprehensive strategic alliance. They will also discuss strengthening the robust South Korea-US combined defense posture and cooperating to establish peace and achieve denuclearization on the Korean Peninsula. The future of the decades-old military alliance is also expected to be in the spotlight as the two countries prepare to participate in their annual Ulchi Freedom Shield joint exercise.
          shortSummary: South Korean President Lee Jae Myung will hold a summit with U.S. President Donald Trump in Washington, focusing on strengthening the South Korea-U.S alliance and establishing peace and denuclearization.
          translation: ''
          translatedTitle: ''
          translatedDescription: ''
          translatedSummary: ''
          locations:
          - country: kr
          - country: kr
            state: '11'
            city: Seoul
          reprint: true
          reprintGroupId: 4e4bf19e89984af1baee7d04776bb9cd
          places: []
          people:
          - wikidataId: Q22686
            name: Donald Trump
          - wikidataId: Q12612463
            name: Lee Jae Myung
    ArticleRefreshJobResponse:
      type: object
      properties:
        jobId:
          type:
          - string
          - 'null'
          format: uuid
        status:
          type:
          - string
          - 'null'
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ArticleRefreshJobArticleResult'
    Coordinate:
      type: object
      properties:
        lat:
          type:
          - number
          - 'null'
          description: Latitude in decimal degrees.
          format: double
        lon:
          type:
          - number
          - 'null'
          description: Longitude in decimal degrees.
          format: double
      description: Geographic coordinates of the place.
    Place:
      type: object
      properties:
        osmId:
          type:
          - string
          - 'null'
          description: OpenStreetMap identifier for the place.
        road:
          type:
          - string
          - 'null'
          description: Road associated with the place.
        quarter:
          type:
          - string
          - 'null'
          description: Quarter associated with the place.
        suburb:
          type:
          - string
          - 'null'
          description: Suburb associated with the place.
        city:
          type:
          - string
          - 'null'
          description: City associated with the place.
        town:
          type:
          - string
          - 'null'
          description: Town associated with the place.
        county:
          type:
          - string
          - 'null'
          description: County associated with the place.
        stateDistrict:
          type:
          - string
          - 'null'
          description: State district associated with the place.
        state:
          type:
          - string
          - 'null'
          description: State or region associated with the place.
        postcode:
          type:
          - string
          - 'null'
          description: Postal code associated with the place.
        country:
          type:
          - string
          - 'null'
          description: Country associated with the place.
        countryCode:
          type:
          - string
          - 'null'
          description: Two-character country code for the place.
        amenity:
          type:
          - string
          - 'null'
          description: Named amenity associated with the place.
        neighbourhood:
          type:
          - string
          - 'null'
          description: Neighborhood associated with the place.
        coordinates:
          allOf:
          - $ref: '#/components/schemas/Coordinate'
      description: Structured geographic places extracted from the article.
    Article:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          description: Canonical URL of the article.
        authorsByline:
          type:
          - string
          - 'null'
          description: Author byline as published by the source.
        articleId:
          type:
          - string
          - 'null'
          description: Unique Perigon identifier for the article.
        clusterId:
          type:
          - string
          - 'null'
          description: Identifier of the story cluster containing the article, when assigned.
        source:
          allOf:
          - $ref: '#/components/schemas/SourceHolder'
        imageUrl:
          type:
          - string
          - 'null'
          description: Primary image URL associated with the article.
        country:
          type:
          - string
          - 'null'
          description: Two-character country code associated with the article.
        language:
          type:
          - string
          - 'null'
          description: ISO 639 two-letter language code for the article.
        pubDate:
          type:
          - string
          - 'null'
          description: Date and time the article was published, in ISO 8601 format.
        addDate:
          type:
          - string
          - 'null'
          description: Date and time the article was added to Perigon, in ISO 8601 format.
        refreshDate:
          type:
          - string
          - 'null'
          description: Date and time the article was last refreshed by Perigon, in ISO 8601 format.
        score:
          type:
          - number
          - 'null'
          description: Search relevance score for the article, when applicable.
          format: float
        title:
          type:
          - string
          - 'null'
          description: Article headline.
        description:
          type:
          - string
          - 'null'
          description: Article description or publisher-provided excerpt.
        content:
          type:
          - string
          - 'null'
          description: Full article body available to Perigon.
        enContentWordCount:
          type:
          - integer
          - 'null'
          description: Word count of the English article content, when available.
          format: int32
        medium:
          type:
          - string
          - 'null'
          description: Primary medium type, such as Article or Video.
        links:
          type:
          - array
          - 'null'
          description: URLs linked from the article content.
          items:
            type: string
            description: URLs linked from the article content.
        labels:
          type:
          - array
          - 'null'
          description: Editorial labels assigned to the article.
          items:
            $ref: '#/components/schemas/LabelHolder'
        eventTypes:
          type:
          - array
          - 'null'
          description: Event types detected in the article.
          items:
            $ref: '#/components/schemas/EventTypeHolder'
        matchedAuthors:
          type:
          - array
          - 'null'
          description: Known journalist records matched to the article byline.
          items:
            $ref: '#/components/schemas/IdNameHolder'
        claim:
          type:
          - string
          - 'null'
          description: Claim identified in fact-check content, when applicable.
        verdict:
          type:
          - string
          - 'null'
          description: Verdict identified in fact-check content, when applicable.
        keywords:
          type:
          - array
          - 'null'
          description: Keywords extracted from the article with their relevance weights.
          items:
            $ref: '#/components/schemas/KeywordHolder'
        topics:
          type:
          - array
          - 'null'
          description: Topics assigned to the article.
          items:
            $ref: '#/components/schemas/TopicHolder'
        categories:
          type:
          - array
          - 'null'
          description: Broad content categories assigned to the article.
          items:
            $ref: '#/components/schemas/CategoryHolder'
        taxonomies:
          type:
          - array
          - 'null'
          description: Google Content Categories assigned to the article with confidence scores.
          items:
            $ref: '#/components/schemas/CategoryWithScoreHolder'
        entities:
          type:
          - array
          - 'null'
          description: Named entities extracted from the article.
          items:
            $ref: '#/components/schemas/EntityHolder'
        companies:
          type:
          - array
          - 'null'
          description: Companies identified in the article.
          items:
            $ref: '#/components/schemas/CompanyHolder'
        sentiment:
          allOf:
          - $ref: '#/components/schemas/SentimentHolder'
        summary:
          type:
          - string
          - 'null'
          description: Generated summary of the article, when available.
        shortSummary:
          type:
          - string
          - 'null'
          description: Short generated summary of the article, when available.
        translation:
          type:
          - string
          - 'null'
          description: Translated article content, when available.
        translatedTitle:
          type:
          - string
          - 'null'
          description: English translation of the article title, when available.
        translatedDescription:
          type:
          - string
          - 'null'
          description: English translation of the article description, when available.
        translatedSummary:
          type:
          - string
          - 'null'
          description: English translation of the article summary, when available.
        locations:
          type:
          - array
          - 'null'
          description: Locations identified as central to the article.
          items:
            $ref: '#/components/schemas/LocationHolder'
        reprint:
          type:
          - boolean
          - 'null'
          description: Whether the article is a reprint of previously published content.
        reprintGroupId:
          type:
          - string
          - 'null'
          description: Identifier grouping the original article with its known reprints.
        places:
          type:
          - array
          - 'null'
          description: Structured geographic places extracted from the article.
          items:
            $ref: '#/components/schemas/Place'
        people:
          type:
          - array
          - 'null'
          description: Known people identified in the article.
          items:
            $ref: '#/components/schemas/PersonHolder'
        cluster:
          allOf:
          - $ref: '#/components/schemas/NewsCluster'
        journalists:
          type:
          - array
          - 'null'
          description: Expanded journalist details, when requested and available.
          items:
            $ref: '#/components/schemas/Journalist'
        highlights:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            description: Matched text fragments grouped by article field.
            items:
              type: string
              description: Matched text fragments grouped by article field.
          description: Matched text fragments grouped by article field.
        vectors:
          type:
          - array
          - 'null'
          description: Vector embeddings associated with the article, when requested.
          items:
            $ref: '#/components/schemas/VectorData'
    StorySearchResult:
      required:
      - numResults
      - results
      - status
      type: object
      properties:
        status:
          type: integer
          format: int32
        numResults:
          type: integer
          format: int64
        results:
          type: array
          items:
            $ref: '#/components/schemas/NewsCluster'
      description: Story search result
      example:
        status: 200
        numResults: 10000
        results:
        - createdAt: '2025-08-12T09:26:15.861525+00:00'
          updatedAt: '2025-08-12T09:47:42.780519+00:00'
          initializedAt: '2025-08-12T09:43:09.364043+00:00'
          id: c9b6bebef14943edb6269c80b1cb51c5
          name: Red Bull Completes Newcastle Rugby Takeover, Rebrands Club
          summary: Red Bull has completed a takeover of the Premiership Rugby club Newcastle Falcons, rebranding the team as Newcastle Red Bulls while keeping them at Kingston Park. The acquisition marks Red Bull's first significant involvement in rugby union and brings fresh investment aimed at elevating the club's competitive potential domestically and in Europe. Steve Diamond will remain as director of rugby, ensuring continuity as the club seeks to compete for trophies in the coming years. Red Bull plans to develop local rugby talent through an enhanced academy program and enhance the fan experience by applying their innovative approach from global sports initiatives. Premiership Rugby CEO Simon Massie-Taylor hailed the takeover as a landmark moment that will add value to both Newcastle and the league, emphasizing Red Bull's expertise in high-performance sports and marketing. The club, established in 1877 and historically known as Newcastle Falcons, aims to leverage Red Bull's global sports portfolio, which includes Formula 1 and various football clubs, to grow its fanbase and player pathway in the North East.
          shortSummary: Energy drink giant Red Bull has completed a takeover of Newcastle Falcons rugby club, rebranding it as Newcastle Red Bulls and keeping it at Kingston Park with Steve Diamond remaining as director of rugby. Red Bull aims to elevate the club's competitive potential, develop local talent through an enhanced academy, and leverage their global sports expertise to boost both the club and the Gallagher Premiership.
          summaryReferences:
          - 66c3a007e2374ffdbbaa70ee5e251693
          - e32349ed5e084f71be1e28733755ed7e
          - 558dc91a9ab04630908404ca4221d2fb
          - f73d2117e50d4cfb8740ed3384b2b330
          - c1c65a3e5bc34ab1ab9f049986a53cc1
          keyPoints:
          - point: The previous owner Semore Kurdi had put the club up for sale at a nominal price of £1 due to financial struggles, signaling the club was on the brink of a financial crisis before Red Bull's takeover.
            references: []
          - point: Newcastle Rugby Ltd highlighted the club’s long history, originally established in 1877 as Gosforth Football Club and undergoing several name changes before becoming Newcastle Falcons in 1996, and now Newcastle Red Bulls in 2025.
            references: []
          - point: Newcastle Falcons have a decorated history, having won five major titles including the Premiership in 1998 and four domestic cups in 1976, 1977, 2001, and 2004.
            references: []
          - point: Red Bull's global sports portfolio includes ownership stakes in multiple football clubs such as RB Leipzig, New York Red Bulls, Red Bull Salzburg, Red Bull Bragantino, and minority stakes in Paris FC and Leeds United, illustrating their extensive experience in sports ownership and management.
            references: []
          - point: Red Bull has a history of working with prominent rugby players such as Springboks captain Siya Kolisi and former England international Jack Nowell, indicating their prior engagement with rugby despite this being their first significant club ownership in rugby union.
            references: []
          sentiment:
            positive: 0.6500967
            negative: 0.112720154
            neutral: 0.23718315
          uniqueCount: 6
          reprintCount: 3
          totalCount: 9
          countries:
          - name: gb
            count: 5
          - name: ca
            count: 3
          - name: za
            count: 1
          topCountries:
          - gb
          topics:
          - name: Rugby
            count: 2
          topTopics:
          - name: Rugby
          categories:
          - name: Sports
            count: 5
          topCategories:
          - name: Sports
          taxonomies:
          - name: /News/Sports News
            count: 8
          - name: /Sports/Team Sports/Rugby
            count: 8
          topTaxonomies:
          - name: /News/Sports News
          - name: /Sports/Team Sports/Rugby
          people:
          - wikidataId: Q15837487
            name: Oliver Mintzlaff
            count: 8
          - wikidataId: Q7612382
            name: Steve Diamond
            count: 5
          - wikidataId: Q7533339
            name: Siya Kolisi
            count: 2
          - wikidataId: Q15731077
            name: Jack Nowell
            count: 2
          - wikidataId: Q7612383
            name: Steve Diamond
            count: 3
          - wikidataId: Q5229992
            name: Dave Thompson
            count: 1
          - wikidataId: Q104535295
            name: Jamie Blamire
            count: 2
          - wikidataId: Q50124849
            name: Callum Chick
            count: 2
          - wikidataId: Q74698940
            name: Tom Christie
            count: 2
          - wikidataId: Q19519831
            name: Max Clark
            count: 1
          topPeople:
          - wikidataId: Q15837487
            name: Oliver Mintzlaff
          - wikidataId: Q7612382
            name: Steve Diamond
          companies:
          - id: d19eef21be0343e4b96c73b85f5afed9
            name: Premiership Rugby
            domains:
            - premiershiprugby.com
            symbols: []
            count: 7
          - id: c28c867e3ec84f569eb0c2c202ffec20
            name: Red Bull GmbH
            domains:
            - redbull.com
            symbols: []
            count: 7
          - id: 1986c4e2c8b54e81af4fbae3e8fbb870
            name: The Raine Group
            domains:
            - raine.com
            symbols: []
            count: 2
          - id: d79a8b400c5c4f12bbbda5b4ac95d882
            name: TNT Sports
            domains:
            - wbd.com
            - discoverysports.com
            symbols: []
            count: 4
          - id: 932cd2db2347407fbda9386cb18307dc
            name: Deloitte
            domains:
            - deloitte.com
            symbols: []
            count: 2
          - id: b40dc389506141a4bcd5ba94f64592f6
            name: Red Bull
            domains:
            - redbullracing.com
            symbols: []
            count: 6
          - id: f1e3e2243cd142408136bd8f43282c4a
            name: City A.M.
            domains:
            - cityam.com
            symbols: []
            count: 1
          - id: c4800bcde1c940d6b13e2022836c10cd
            name: Getty Images Holdings, Inc.
            domains:
            - gettyimages.com
            symbols:
            - GETY
            count: 2
          - id: 1bc09603d6cd4aeba01c8c7762d8cda6
            name: Reuters
            domains:
            - reuters.com
            symbols: []
            count: 1
          - id: fb9806c8e362406ea89d48d31dcf50a7
            name: Formula One Group
            domains:
            - libertymedia.com
            symbols:
            - 0JUJ.L
            - FWONA
            - FWONB
            - FWONK
            count: 1
          - id: 01a4555587844344a5b0eef0854ee0ad
            name: Guardian Media Group
            domains:
            - theguardian.com
            symbols: []
            count: 1
          topCompanies:
          - id: d19eef21be0343e4b96c73b85f5afed9
            name: Premiership Rugby
            domains:
            - premiershiprugby.com
            symbols: []
          - id: c28c867e3ec84f569eb0c2c202ffec20
            name: Red Bull GmbH
            domains:
            - redbull.com
            symbols: []
          - id: b40dc389506141a4bcd5ba94f64592f6
            name: Red Bull
            domains:
            - redbullracing.com
            symbols: []
          locations:
          - state: ENG
            city: Newcastle upon Tyne
            count: 2
          topLocations:
          - state: ENG
            city: Newcastle upon Tyne
    CategoryWithScoreHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Full taxonomy category path.
        score:
          type:
          - number
          - 'null'
          description: Confidence score for the category assignment.
          format: double
      description: Google Content Categories assigned to the article with confidence scores.
    EntityHolder:
      type: object
      properties:
        data:
          type:
          - string
          - 'null'
          description: Text value of the extracted entity.
        type:
          type:
          - string
          - 'null'
          description: Entity type, such as PERSON, ORGANIZATION, or LOCATION.
        mentions:
          type:
          - integer
          - 'null'
          description: Number of times the entity appears in the article.
          format: int32
      description: Named entities extracted from the article.
    EventTypeHolder:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Detected event name.
        type:
          type:
          - string
          - 'null'
          description: Detected event classification.
      description: Event types detected in the article.
    KeyPoint:
      type: object
      properties:
        point:
          type:
          - string
          - 'null'
          description: A key fact or development identified in the content.
        references:
          type:
          - array
          - 'null'
          description: Article IDs supporting the key point.
          items:
            type: string
            description: Article IDs supporting the key point.
      description: Key facts and developments identified in the story.
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer