openapi: 3.0.3
info:
  title: Meltwater API v4
  description: |
    The Meltwater Public API v4 provides unified access to content search,
    content export, and analytics across Meltwater owned social and Explore+
    data sources, plus LLM lens prompts.

    ## Key Features
    - Unified query interface across all data sources
    - Consistent pagination and error handling
    - Comprehensive analytics with nested analysis support

    ## Core Journeys
    1. **Search → Paginate → Refine → Export → Poll → Download**
    2. **Analytics Request** with multiple analyses and shared filters
  contact:
    name: Meltwater API Support
    url: https://developer.meltwater.com/
    email: support@api.meltwater.com
  version: 4.0.0-beta
servers:
  - url: https://api.meltwater.com/v4
    description: Production server
security:
  - apiKey: []
  - bearerAuth: []
tags:
  - name: Export
    description: Export content and manage export jobs
paths:
  /content/export:
    get:
      tags:
        - Export
      summary: List exports
      description: Get a list of all content exports.
      operationId: listExports
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - name: provider
          in: query
          required: true
          description: Data source provider to list exports for.
          schema:
            type: string
            enum:
              - explore_plus
        - name: schedule_type
          in: query
          required: false
          description: Filter exports by schedule type.
          schema:
            type: string
            enum:
              - onetime
              - recurring
        - name: page
          in: query
          required: false
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
        - name: page_size
          in: query
          required: false
          description: Number of items per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: List of exports
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - page
                  - page_size
                  - data
                properties:
                  count:
                    type: integer
                    description: Total number of exports matching the query.
                  page:
                    type: integer
                    description: Current page number (1-based).
                  page_size:
                    type: integer
                    description: Number of items per page.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/export'
              example:
                count: 2
                page: 1
                page_size: 10
                data:
                  - provider: explore_plus
                    type: onetime
                    tz: UTC
                    period:
                      start: '2026-04-01T00:00:00'
                      end: '2026-04-30T23:59:59'
                    config:
                      id: 99
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-one-time/99?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-04-01T00:05:00Z'
                      status: FINISHED
                      status_reason: ''
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
                  - provider: explore_plus
                    type: recurring
                    tz: UTC
                    period:
                      cron: 0 6 15 8 *
                    config:
                      id: 100
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-recurring/100?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-05-01T00:05:00Z'
                      next_run_date: '2026-08-15T06:00:00Z'
                      status: ACTIVE
                      status_reason: ''
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Export
      summary: Create export
      description: Create a new content export job.
      operationId: createExport
      parameters:
        - $ref: '#/components/parameters/CompanyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/export-query'
            examples:
              oneTime:
                summary: One-time export over a fixed period
                value:
                  provider: explore_plus
                  type: onetime
                  tz: UTC
                  period:
                    start: '2026-04-01T00:00:00'
                    end: '2026-04-30T23:59:59'
                  query:
                    searches:
                      all:
                        - 12345
                  output:
                    format: json
                    template: api.json
              recurring:
                summary: Recurring export on a cron schedule
                value:
                  provider: explore_plus
                  type: recurring
                  tz: UTC
                  period:
                    cron: 0 6 15 8 *
                    window_size: 1
                    window_unit: day
                  query:
                    searches:
                      all:
                        - 12345
                  output:
                    format: json
                    template: api.json
      responses:
        '201':
          description: Export created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export'
              examples:
                oneTime:
                  summary: One-time export (processing)
                  value:
                    provider: explore_plus
                    type: onetime
                    tz: UTC
                    period:
                      start: '2026-04-01T00:00:00'
                      end: '2026-04-30T23:59:59'
                    config:
                      id: 1
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-one-time/1?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-04-01T00:00:00Z'
                      status: PENDING
                      status_reason: Export run has not completed yet
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
                recurring:
                  summary: Recurring export (scheduled)
                  value:
                    provider: explore_plus
                    type: recurring
                    tz: UTC
                    period:
                      cron: 0 6 15 8 *
                      window_size: 1
                      window_unit: day
                    config:
                      id: 2
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-recurring/2?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-04-01T00:00:00Z'
                      next_run_date: '2026-08-15T06:00:00Z'
                      status: ACTIVE
                      status_reason: ''
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
        '400':
          $ref: '#/components/responses/Error'
  /content/export/{exportId}:
    get:
      tags:
        - Export
      summary: Get export details
      description: Get details of a specific export job.
      operationId: getExport
      parameters:
        - name: exportId
          in: path
          required: true
          description: Export job id.
          schema:
            type: integer
        - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: Export details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export'
              examples:
                oneTime:
                  summary: One-time export (completed)
                  value:
                    provider: explore_plus
                    type: onetime
                    tz: UTC
                    period:
                      start: '2026-04-01T00:00:00'
                      end: '2026-04-30T23:59:59'
                    config:
                      id: 99
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-one-time/99?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-04-01T00:05:00Z'
                      status: FINISHED
                      status_reason: ''
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
                recurring:
                  summary: Recurring export with run history
                  value:
                    provider: explore_plus
                    type: recurring
                    tz: UTC
                    period:
                      cron: 0 6 15 8 *
                    config:
                      id: 100
                      company_id: 0a12bc34de56f07890ab12cd
                      url: https://exports.meltwater.io/v4/explore-plus-recurring/100?data_key=EXAMPLE_DATA_KEY
                      created_at: '2026-04-01T00:00:00Z'
                      updated_at: '2026-05-01T00:05:00Z'
                      next_run_date: '2026-08-15T06:00:00Z'
                      status: ACTIVE
                      status_reason: ''
                    query:
                      searches:
                        all:
                          - id: 12345
                            name: Brand mentions
                    output:
                      format: json
                      template: api.json
                    history:
                      - status: FINISHED
                        period:
                          start: '2026-04-01T00:00:00'
                          end: '2026-04-30T23:59:59'
                        created_at: '2026-05-01T00:00:00Z'
                        updated_at: '2026-05-01T00:05:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Export
      summary: Delete export
      description: Delete an export job.
      operationId: deleteExport
      parameters:
        - name: exportId
          in: path
          required: true
          description: Export job id.
          schema:
            type: integer
        - $ref: '#/components/parameters/CompanyId'
      responses:
        '204':
          description: Export deleted
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    period:
      type: object
      description: Time range for the query. One-time queries/exports use start + end; recurring exports instead use cron (optionally with window_size + window_unit) and omit start/end. Exactly one of those two forms must be supplied.
      oneOf:
        - required:
            - start
            - end
        - required:
            - cron
      properties:
        start:
          type: string
          description: Start of the date range (ISO 8601 datetime without timezone, e.g. 2024-01-01T00:00:00). Required for one-time queries and exports.
        end:
          type: string
          description: End of the date range (ISO 8601 datetime without timezone, e.g. 2024-01-31T23:59:59). Required for one-time queries and exports.
        window_size:
          type: integer
          description: Rolling window size for recurring exports. Optional; combined with window_unit to define the rolling range.
        window_unit:
          type: string
          description: Unit for the rolling window (e.g. day, week) for recurring exports. Optional; the API applies a default when omitted.
        cron:
          type: string
          description: Cron expression scheduling a recurring export. Required for recurring exports.
    detailed-breakdown-item:
      type: object
      description: A selected resource with its resolved id and name.
      properties:
        id:
          type: integer
        name:
          type: string
    detailed-breakdown:
      type: object
      description: Selection broken into all / any / none groups. In export responses each entry is enriched with the resolved id and name of the selected resource.
      properties:
        all:
          type: array
          items:
            $ref: '#/components/schemas/detailed-breakdown-item'
        any:
          type: array
          items:
            $ref: '#/components/schemas/detailed-breakdown-item'
        none:
          type: array
          items:
            $ref: '#/components/schemas/detailed-breakdown-item'
    export:
      type: object
      description: An export job, as returned by the create, list and get export endpoints.
      properties:
        provider:
          type: string
          description: Data source provider the export runs against.
          enum:
            - explore_plus
        type:
          type: string
          description: Export schedule type.
          enum:
            - onetime
            - recurring
        tz:
          type: string
          description: IANA timezone the export was scheduled in.
        period:
          $ref: '#/components/schemas/period'
        config:
          type: object
          description: Server-assigned configuration and status for the export job.
          properties:
            id:
              type: integer
              description: Unique export job id.
            company_id:
              type: string
            workspace_id:
              type: string
            url:
              type: string
              format: uri
              description: Download URL for the export output. Populated once the job has produced data.
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            next_run_date:
              type: string
              format: date-time
              description: Next scheduled run. Only present for recurring exports.
            status:
              type: string
              description: Current export status.
              enum:
                - ACTIVE
                - PENDING
                - FINISHED
                - PAUSED
                - FAILED
                - CANCELLED
                - EXPIRED
            status_reason:
              type: string
              description: Human-readable detail for the current status (e.g. why it is pending, paused or failed). Empty when not applicable.
        query:
          type: object
          description: The submitted query, echoed back with selected resources resolved to id + name.
          properties:
            searches:
              $ref: '#/components/schemas/detailed-breakdown'
            tags:
              $ref: '#/components/schemas/detailed-breakdown'
            filters:
              type: object
              description: Filters applied to the query.
              additionalProperties: true
        output:
          type: object
          description: Output configuration for the export.
          properties:
            format:
              type: string
              enum:
                - json
                - csv
                - xlsx
            template:
              type: string
            sample:
              type: object
              description: Sampling configuration, when the export is sampled.
              properties:
                count:
                  type: integer
                  description: Number of documents sampled.
        history:
          type: array
          description: Run history. Only included on the get-export endpoint for recurring exports.
          items:
            type: object
            properties:
              status:
                type: string
                description: Status of this individual run.
                enum:
                  - ACTIVE
                  - PENDING
                  - FINISHED
                  - PAUSED
                  - FAILED
                  - CANCELLED
                  - EXPIRED
              period:
                type: object
                properties:
                  start:
                    type: string
                  end:
                    type: string
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
    error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - INVALID_QUERY
            - RESOURCE_NOT_FOUND
            - UNAUTHORIZED
            - FORBIDDEN
            - RATE_LIMITED
            - INTERNAL_ERROR
            - VALIDATION_ERROR
            - PROVIDER_ERROR
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error context
          additionalProperties: true
        request_id:
          type: string
          description: Unique request identifier for debugging
    id-filter:
      type: object
      properties:
        all:
          type: array
          items:
            type: integer
        any:
          type: array
          items:
            type: integer
        none:
          type: array
          items:
            type: integer
    string-filter:
      type: object
      properties:
        all:
          type: array
          items:
            type: string
        any:
          type: array
          items:
            type: string
        none:
          type: array
          items:
            type: string
    source:
      type: string
      description: Content source. Accepted values for Explore+ (case-insensitive).
      enum:
        - facebook
        - instagram
        - reddit
        - blogs
        - product_reviews
        - forums
        - comments
        - x
        - wechat
        - sina_weibo
        - pinterest
        - twitch
        - tiktok
        - douyin
        - little_red_book
        - google_reviews
        - threads
        - kakaotalk
        - linevoom
        - news_online
        - news_print
        - news_app
        - broadcast
        - youku
        - bilibili
        - rss
        - youtube
        - social_reviews
    source-filter:
      type: object
      description: Source filter broken into all / any / none groups, restricted to supported sources.
      properties:
        all:
          type: array
          items:
            $ref: '#/components/schemas/source'
        any:
          type: array
          items:
            $ref: '#/components/schemas/source'
        none:
          type: array
          items:
            $ref: '#/components/schemas/source'
    country:
      type: string
      description: ISO 3166-1 alpha-2 country code (e.g. us, gb, de). Case-insensitive on input.
      pattern: ^[A-Za-z]{2}$
    country-filter:
      type: object
      description: Country filter broken into all / any / none groups.
      properties:
        all:
          type: array
          items:
            $ref: '#/components/schemas/country'
        any:
          type: array
          items:
            $ref: '#/components/schemas/country'
        none:
          type: array
          items:
            $ref: '#/components/schemas/country'
    sentiment:
      type: string
      description: Sentiment value (case-insensitive).
      enum:
        - positive
        - negative
        - neutral
    sentiment-filter:
      type: object
      description: Sentiment filter broken into all / any / none groups.
      properties:
        all:
          type: array
          items:
            $ref: '#/components/schemas/sentiment'
        any:
          type: array
          items:
            $ref: '#/components/schemas/sentiment'
        none:
          type: array
          items:
            $ref: '#/components/schemas/sentiment'
    explore-plus-query:
      type: object
      description: Query for an Explore+ content export. Select saved searches with `searches` (required), and optionally narrow results with `filters`.
      required:
        - searches
      properties:
        searches:
          type: object
          description: Saved search IDs to export.
          properties:
            all:
              type: array
              items:
                type: integer
            any:
              type: array
              items:
                type: integer
            none:
              type: array
              items:
                type: integer
        filters:
          type: object
          description: Filters accepted by Explore+ exports.
          properties:
            tags:
              $ref: '#/components/schemas/id-filter'
            languages:
              $ref: '#/components/schemas/string-filter'
            filter_sets:
              $ref: '#/components/schemas/id-filter'
            custom_fields:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/id-filter'
              description: Custom field filters keyed by custom field ID.
            author_lists:
              $ref: '#/components/schemas/id-filter'
            sources:
              $ref: '#/components/schemas/source-filter'
            countries:
              $ref: '#/components/schemas/country-filter'
            sentiments:
              $ref: '#/components/schemas/sentiment-filter'
    export-query:
      type: object
      description: Request body for creating a content export.
      required:
        - provider
        - type
        - tz
        - period
        - query
        - output
      properties:
        provider:
          type: string
          description: Data source provider to export.
          enum:
            - explore_plus
        type:
          type: string
          description: Export schedule type. `onetime` runs once over the given period; `recurring` runs on a schedule (see period.cron / period.window_size).
          enum:
            - onetime
            - recurring
        tz:
          type: string
          description: IANA timezone name (e.g. America/New_York, UTC)
        period:
          $ref: '#/components/schemas/period'
        query:
          $ref: '#/components/schemas/explore-plus-query'
        output:
          type: object
          required:
            - format
            - template
          description: Output configuration
          properties:
            format:
              type: string
              enum:
                - json
                - csv
                - xlsx
              description: Output format
            template:
              type: string
              description: Output template name
            sample:
              type: object
              description: Optional sampling configuration.
              properties:
                count:
                  type: integer
                  description: Number of documents to sample.
                  minimum: 0
                  maximum: 2000000
  parameters:
    CompanyId:
      name: company_id
      in: query
      description: Company which owns the resource. If not specified, your default company is used.
      required: false
      schema:
        type: string
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            code: RESOURCE_NOT_FOUND
            message: Not Found
            request_id: 123e4567-e89b-12d3-a456-426614174000
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            code: UNAUTHORIZED
            message: Not Authorized
            request_id: 123e4567-e89b-12d3-a456-426614174000
x-tagGroups:
  - name: Content
    tags:
      - Export
