> ## Documentation Index > Fetch the complete documentation index at: https://docs.peakmetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # Narratives > Narratives are AI-powered clusters of related mentions that share common themes or storylines. PeakMetrics' narrative clustering algorithms distill thousands of mentions into easily digestible narratives, helping you quickly understand key themes without manual analysis. All standard mention filters can be applied to narrow the results. ## OpenAPI ````yaml /api/api_docs.yaml get /workspaces/{workspaceId}/narratives openapi: 3.1.0 info: title: PeakMetrics API description: > The PeakMetrics API provides programmatic access to narrative intelligence data. Access millions of mentions across news, social media, and online platforms, enriched with custom AI-powered smart categories and over 50 metadata properties. The API enables you to identify, analyze, and act on emerging narratives in real-time. version: 2.0.0 servers: - url: https://api.peakmetrics.com description: Main (production) server security: - BearerAuth: [] tags: - name: Authorization - name: Workspaces - name: Folders - name: Channels - name: Custom Channels - name: Custom Enrichments description: > Custom enrichments let you push external context about mentions into PeakMetrics, attached to individual mentions and used alongside all other mention metadata across the platform. Once written, enrichment values feed into narrative analysis, workspace summaries, and notifications, and are available through the customer API and the MCP server. Your team manages its own custom enrichments through the API: create one with `POST /customEnrichments`, list them with `GET /customEnrichments`, rename one or replace its option list with `PUT /customEnrichments/{enrichmentId}`, retire one with `DELETE /customEnrichments/{enrichmentId}`, and push values for individual mentions with `PUT /mentions/customEnrichments`. paths: /workspaces/{workspaceId}/narratives: get: tags: - Workspaces summary: Narratives description: > Narratives are AI-powered clusters of related mentions that share common themes or storylines. PeakMetrics' narrative clustering algorithms distill thousands of mentions into easily digestible narratives, helping you quickly understand key themes without manual analysis. All standard mention filters can be applied to narrow the results. parameters: - $ref: '#/components/parameters/WorkspaceId' - in: query name: limit required: false schema: type: integer maximum: 1000 minimum: 1 description: The maximum number of narratives to return, default 1000. - in: query name: offset required: false schema: type: integer minimum: 0 description: The number of narratives to skip before returning, default 0. - in: query name: sort required: false schema: type: string enum: - relevancy - mentionCount - created - favorite description: The field to sort the narratives by descending, default relevancy. - $ref: '#/components/parameters/Since' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/Channels' - $ref: '#/components/parameters/FilterExpression' - $ref: '#/components/parameters/Domains' - $ref: '#/components/parameters/Authors' - $ref: '#/components/parameters/Languages' - $ref: '#/components/parameters/BotRatings' - $ref: '#/components/parameters/SmartCategories' - $ref: '#/components/parameters/CustomEnrichments' - $ref: '#/components/parameters/MentionTypeSocialMedia' - $ref: '#/components/parameters/MentionTypeNews' - $ref: '#/components/parameters/MentionTypePodcasts' - $ref: '#/components/parameters/PublisherGeographySourceCountry' - $ref: '#/components/parameters/PublisherGeographySourceRegion' - $ref: '#/components/parameters/PublisherGeographySourceSubRegion' responses: '200': description: A JSON array of narrative objects content: application/json: schema: type: array items: type: object properties: id: type: integer minimum: 1 description: The unique identifier for the narrative. title: type: string description: The AI generated title for the narrative. isFavorite: type: boolean description: Favorited status of narrative for requesting user. aggregations: type: object properties: mentionCount: type: integer minimum: 0 description: >- The number of mentions that are part of the narrative. avgSentiment: type: number minimum: 0 maximum: 0 deprecated: true description: > **Deprecated — always returns `0`** Contact support@peakmetrics.com to set up a custom favorability smart category as an upgraded replacement. relevancyScore: type: number minimum: 0 maximum: 100 description: >- The probability that this narrative is relevant to the provided workspace ID query, from 0 to 100. created: type: string format: date-time description: The date and time the narrative was created. summary: type: string description: The summary of the given narrative. tags: type: array description: Tags assigned by team members to the narrative. items: type: object properties: id: type: number description: Unique tag for given narrative tag. name: type: string description: Tag name given by user. createdDate: type: string format: date-time description: >- The date the narrative tag was assigned to the given narrative. components: parameters: WorkspaceId: name: workspaceId in: path required: true schema: type: integer minimum: 1 description: The unique identifier for the workspace. Since: name: since in: query required: true schema: type: string format: date-time description: The minimum published date of the mentions to return. example: '2024-01-01T00:00:00Z' To: name: to in: query required: true schema: type: string format: date-time description: The maximum published date of the mentions to return. example: '2024-01-01T23:59:59Z' Channels: name: channels in: query required: false schema: type: array items: type: string enum: - blogsdiscussions - bluesky - facebook - instagram - news - reddit - redditComment - telegram - threads - tiktok - twitter - vk - weibo - youtube description: Filter to mentions that are part of the provided channel. example: '[''twitter'', ''news'']' FilterExpression: name: filter_expression in: query required: false schema: type: string description: > A keyword search string applied against mention content. Supports Boolean operators (AND, OR, NOT) and quoted phrases for exact matching. Field-scoped expressions are also supported (e.g., `title:word` or `text:phrase`). This filter is applied in addition to the workspace query and any other filters. Use this for ad-hoc keyword narrowing without modifying the workspace configuration. example: (title:word OR text:word2) AND (title:word4 OR text:word3) Domains: name: domains in: query required: false schema: type: array items: type: string description: | Filter to mentions published on the provided domains. Multiple values are combined with OR logic. example: '[''nytimes.com'', ''reuters.com'']' Authors: name: authors in: query required: false schema: type: array items: type: string description: | Filter to mentions attributed to the provided authors. Multiple values are combined with OR logic. example: '[''@exampleuser'', ''Jane Doe'']' Languages: name: languages in: query required: false schema: type: array items: type: string description: | Filter to mentions in the provided languages, specified as two-letter ISO 639-1 codes. Multiple values are combined with OR logic. example: '[''en'', ''es'']' BotRatings: name: bot_ratings in: query required: false schema: type: array items: type: string enum: - none - further_investigation - very_unlikely - unlikely - potential - likely - very_likely - almost_certain description: > Filter by bot detection confidence level. Bot detection analyzes social media accounts to identify automated or coordinated inauthentic behavior. Multiple values are combined with OR logic. example: '[''likely'', ''very_likely'', ''almost_certain'']' SmartCategories: name: smart_categories in: query required: false schema: type: array items: type: string description: > Filter by Smart Category classification results. Smart Categories are custom AI-powered classifiers configured per workspace (e.g., sentiment models, topic classifiers, violent rhetoric detection). Each value is a composite string in the format `{enrichmentId}:{categoryKey}`, where `enrichmentId` identifies the Smart Category model and `categoryKey` identifies the classification label (e.g., `c0`, `c1`, `c2`). Available enrichment IDs and their category key mappings can be discovered via `GET /workspaces/{workspaceId}/available-filters`. Multiple values are combined with OR logic. example: '[''244:c0'', ''294:c1'']' CustomEnrichments: name: custom_enrichments in: query required: false schema: type: array items: type: string description: > Filter by custom enrichment values. Custom enrichments are structured fields provisioned for your team that attach external context to mentions. Each value is a composite string in the format `{enrichment_id}:{value}`, where `enrichment_id` identifies the custom enrichment and `value` is the category value to match (e.g., `1681:Substantiated`). Available custom enrichments and their recorded values for this workspace can be discovered via `GET /workspaces/{workspaceId}/available-filters` under `custom_enrichments`. Multiple values are combined with OR logic. example: '[''1681:Substantiated'', ''1681:Mixed'']' MentionTypeSocialMedia: name: mention_type.social_media in: query required: false schema: type: array items: type: string enum: - original_posts - reposts - comments - quoting_posts description: > Filter by social media post type. Use the values returned by `GET /workspaces/{workspaceId}/available-filters` under `mention_type.social_media.options`. Multiple values from the same sub-filter are combined with OR logic. example: '[''original_posts'', ''reposts'']' MentionTypeNews: name: mention_type.news in: query required: false schema: type: array items: type: string enum: - news description: | Filter to news mention type. Use the values returned by `GET /workspaces/{workspaceId}/available-filters` under `mention_type.news.options`. Multiple values are combined with OR logic. example: '[''news'']' MentionTypePodcasts: name: mention_type.podcasts in: query required: false schema: type: array items: type: string enum: - podcasts description: > Filter to podcast mention types. Use the values returned by `GET /workspaces/{workspaceId}/available-filters` under `mention_type.podcasts.options`. Multiple values are combined with OR logic. example: '[''podcasts'']' PublisherGeographySourceCountry: name: publisher_geography.source_country in: query required: false schema: type: array items: type: string description: > Filter by the publisher's country of origin. Primarily applicable to news mentions. Country names should match the values returned by `GET /workspaces/{workspaceId}/available-filters`. Multiple values are combined with OR logic. example: '[''United States'', ''United Kingdom'']' PublisherGeographySourceRegion: name: publisher_geography.source_region in: query required: false schema: type: array items: type: string enum: - Africa - Americas - Asia - Europe - Oceania description: | Filter by the publisher's geographic region. Primarily applicable to news mentions. Multiple values are combined with OR logic. example: '[''Americas'', ''Europe'']' PublisherGeographySourceSubRegion: name: publisher_geography.source_sub_region in: query required: false schema: type: array items: type: string enum: - Australia and New Zealand - Caribbean - Central America - Central Asia - Eastern Africa - Eastern Asia - Eastern Europe - Melanesia - Micronesia - Middle Africa - Northern Africa - Northern America - Northern Europe - Polynesia - South America - South-Eastern Asia - Southern Africa - Southern Asia - Southern Europe - Western Africa - Western Asia - Western Europe description: | Filter by the publisher's geographic subregion. Primarily applicable to news mentions. Multiple values are combined with OR logic. example: '[''Northern America'', ''Northern Europe'']' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````