Meltwater Listening Search Management API

openapi: 3.0.3
info:
  title: Meltwater Account Management Listening Search Management API
  description: The Meltwater Public API
  contact:
    name: Meltwater Support
    url: https://developer.meltwater.com/
    email: support@api.meltwater.com
  version: '1.0'
servers:
- url: https://api.meltwater.com
security:
- apikey: []
tags:
- name: Listening Search Management
  description: Manage Saved Searches
  parent: Listening
paths:
  /v3/searches:
    get:
      tags:
      - Listening Search Management
      summary: Get a list of all your searches
      operationId: list_searches
      parameters:
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      - name: query_type
        in: query
        description: Only return searches of the specified query type, if omitted searches of all query types will be returned
        required: false
        schema:
          type: string
          enum:
          - boolean
          - keyword
          - combined
      - name: expand_combined
        in: query
        description: For combined searches, show whether the ids belongs to a search, filter set or custom category
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: List of Searches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchListResponse'
              examples:
                Search List:
                  summary: Search listing
                  value:
                    searches:
                    - updated: '2020-08-23T08:25:56Z'
                      id: 1025
                      name: Electric Cars
                    - updated: '2020-08-23T08:25:56Z'
                      id: 1027
                      name: Pokemon
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
    post:
      tags:
      - Listening Search Management
      summary: Create a search
      operationId: create_search
      parameters:
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      requestBody:
        description: A single search request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleSearchRequest'
            examples:
              Boolean Search:
                summary: Boolean Search
                value:
                  search:
                    name: Boolean Search
                    query:
                      filter_set:
                        id: 123
                        type: saved
                      case_sensitivity: 'yes'
                      boolean: Tesla OR (Volvo NEAR electric)
                      type: boolean
              Keyword Search:
                summary: Keyword Search
                value:
                  search:
                    name: Keyword Search
                    query:
                      filter_set:
                        id: 123
                        type: saved
                      case_sensitivity: hybrid
                      not_keywords:
                      - Vodka
                      any_keywords:
                      - Tesla
                      - Volvo
                      all_keywords:
                      - Car
                      type: keyword
              Combined Search:
                summary: Combined Search
                value:
                  search:
                    name: Combined Search
                    query:
                      filter_set:
                        id: 123
                        type: saved
                      not_searches:
                      - 1
                      any_searches:
                      - 2
                      all_searches:
                      - 3
                      type: combined
        required: true
      responses:
        '201':
          description: A single Search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSearch'
              examples:
                Boolean Search:
                  summary: Boolean Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1025
                      name: Electric Cars
                      query:
                        filter_set: null
                        case_sensitivity: false
                        boolean: cars AND electric
                Keyword Search:
                  summary: Keyword Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1026
                      name: Pokemon
                      query:
                        filter_set:
                          id: 123456
                          name: my filter set
                          subtype: custom
                          type: saved
                        case_sensitivity: 'no'
                        not_keywords: []
                        any_keywords:
                        - Pokemon
                        - Pokémon
                        all_keywords: []
                        type: keyword
                Combined Search:
                  summary: Combined Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56.000Z'
                      id: 1028
                      name: Meltwater Combined
                      query:
                        filter_set: null
                        case_sensitivity: false
                        not_searches: []
                        any_searches: []
                        all_searches:
                        - 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
  /v3/searches/{id}:
    get:
      tags:
      - Listening Search Management
      summary: Get an individual search
      operationId: get_search
      parameters:
      - name: id
        in: path
        description: Search id
        required: true
        schema:
          type: integer
          format: int64
        example: 1234
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      - name: expand_combined
        in: query
        description: For combined searches, show whether the ids belongs to a search, filter set or custom category
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A single Search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSearch'
              examples:
                Boolean Search:
                  summary: Boolean Search with a Query
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1024
                      name: Electric Cars
                      query:
                        filter_set: null
                        case_sensitivity: 'no'
                        boolean: Tesla OR (Volvo NEAR electric)
                        type: boolean
                Boolean Search with hidden Query:
                  summary: Boolean Search with hidden Query
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1025
                      name: Electric Cars
                Keyword Search:
                  summary: Keyword Search with a Query
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1026
                      name: Pokemon
                      query:
                        filter_set:
                          id: 123456
                          name: my filter set
                          subtype: custom
                          type: saved
                        case_sensitivity: 'no'
                        not_keywords: []
                        any_keywords:
                        - Pokemon
                        - Pokémon
                        all_keywords: []
                        type: keyword
                Keyword Search No Query:
                  summary: Keyword Search with hidden Query
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1027
                      name: Pokemon
                Combined Search:
                  summary: Combined Search with a Query
                  value:
                    search:
                      updated: '2020-08-23T08:25:56.000Z'
                      id: 1028
                      name: Meltwater Combined
                      query:
                        filter_set: null
                        case_sensitivity: false
                        not_searches: []
                        any_searches: []
                        all_searches:
                        - 1
                Combined Search No Query:
                  summary: Combined Search with hidden Query
                  value:
                    search:
                      updated: '2020-03-25T00:00:00Z'
                      id: 1028
                      name: Meltwater Combined
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
    put:
      tags:
      - Listening Search Management
      summary: Update an individual search
      operationId: update_search
      parameters:
      - name: id
        in: path
        description: Search id
        required: true
        schema:
          type: integer
          format: int64
        example: 1234
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      requestBody:
        description: A single search request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleSearchRequest'
            examples:
              Keyword Search:
                summary: Keyword Search
                value:
                  search:
                    name: Keyword Search
                    query:
                      filter_set: null
                      case_sensitivity: false
                      not_keywords:
                      - Tesla
                      any_keywords:
                      - Twitter
                      all_keywords:
                      - Musk
                      type: keyword
              Boolean Search:
                summary: Boolean Search
                value:
                  search:
                    name: Boolean Search
                    query:
                      filter_set:
                        id: 123456
                        name: my filter set
                        subtype: custom
                        type: saved
                      case_sensitivity: 'yes'
                      boolean: Tesla OR (Volvo NEAR electric)
                      type: boolean
              Combined Search:
                summary: Combined Search
                value:
                  search:
                    name: Combined Search
                    query:
                      filter_set:
                        id: 123
                        type: saved
                      not_searches:
                      - 1
                      any_searches:
                      - 2
                      all_searches:
                      - 3
                      type: combined
        required: true
      responses:
        '200':
          description: A single Search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSearch'
              examples:
                Boolean Search:
                  summary: Boolean Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1025
                      name: Electric Cars
                      query:
                        filter_set: null
                        case_sensitivity: false
                        boolean: cars AND electric
                Keyword Search:
                  summary: Keyword Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56Z'
                      id: 1026
                      name: Pokemon
                      query:
                        filter_set:
                          id: 123456
                          name: my filter set
                          subtype: custom
                          type: saved
                        case_sensitivity: 'no'
                        not_keywords: []
                        any_keywords:
                        - Pokemon
                        - Pokémon
                        all_keywords: []
                        type: keyword
                Combined Search:
                  summary: Combined Search
                  value:
                    search:
                      updated: '2020-08-23T08:25:56.000Z'
                      id: 1028
                      name: Meltwater Combined
                      query:
                        filter_set: null
                        case_sensitivity: false
                        not_searches: []
                        any_searches: []
                        all_searches:
                        - 1
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
    delete:
      tags:
      - Listening Search Management
      summary: Delete an individual search
      operationId: delete_search
      parameters:
      - name: id
        in: path
        description: Search id
        required: true
        schema:
          type: integer
          format: int64
        example: 1234
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/MissingResourceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/InvalidPermissionsResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/UnprocessableEntityCompanyId'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            '*/*':
              schema:
                $ref: '#/components/schemas/ServiceUnavailable'
      security:
      - apikey: []
      description: ''
  /v3/searches/{id}/count:
    get:
      tags:
      - Listening Search Management
      summary: Get an approximate count of results for the search over a particular period
      operationId: search_count
      parameters:
      - name: id
        in: path
        description: Search id
        required: true
        schema:
          type: integer
          format: int64
        example: 1234
      - name: company_id
        in: query
        description: Company which owns the given search. If not specified your default company is used.
        required: false
        schema:
          type: string
      - name: start_date
        in: query
        description: 'The start date of the search to count result for. Default: `two weeks ago` in ISO8601 format.'
        required: false
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: 'The end date of the search to count result for. Default: `now` in ISO8601 format.'
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Search Count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              example:
                count:
                  total: 901382
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
  /v3/tags:
    get:
      tags:
      - Listening Search Management
      summary: Get a list of all your tags
      operationId: list_tags
      parameters:
      - name: company_id
        in: query
        description: Company which owns the given tags. If not specified your default company is used.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of Tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
              example:
                tags:
                - id: 123456
                  name: my tag
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
      description: ''
    post:
      tags:
      - Listening Search Management
      summary: Create a new tag
      description: Create a new tag for tagging documents. Tag names must be unique and a maximum of 128 characters.
      parameters:
      - name: company_id
        in: query
        description: Company which will own the new tag. If not specified, your default company is used.
        schema:
          type: string
      requestBody:
        description: Tag
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTagRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTagResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - apikey: []
  /v3/tags/{tag_id}:
    delete:
      tags:
      - Listening Search Management
      summary: Delete an existing tag.
      description: Deletes a given tag. Any documents that possess this tag will have it removed following tag deletion.
      parameters:
      - name: tag_id
        in: path
        description: Tag ID
        required: true
        schema:
          type: integer
      - name: company_id
        in: query
        description: Company which owns the tag to be deleted. If not specified, your default company is used.
        schema:
          type: string
      responses:
        '204':
          description: No Content
          content: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apikey: []
  /v3/documents/add_tags:
    post:
      tags:
      - Listening Search Management
      summary: Add tags to documents
      operationId: add_tags
      description: Triggers a request to add a list of specified tags to a given set of documents. This is an asynchronous operation.
      parameters:
      - name: company_id
        in: query
        description: Set the company where the change will be applied
        schema:
          type: string
      requestBody:
        required: true
        description: 'This body must contain two fields: `document_ids`, an array of strings representing the IDs of the documents from which tags should be added, and `tags`, an array of objects where each object has an id (integer) or name (string) representing the tags to be added. Each document in `document_ids` will have the specified `tags` added.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTagsPayload'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MWAPIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MWAPIError'
      security:
      - JWT: []
  /v3/documents/remove_tags:
    post:
      tags:
      - Listening Search Management
      summary: Remove tags from documents
      operationId: remove_tags
      description: Triggers a request to remove a list of specified tags from a given set of documents. This is an asynchronous operation.
      parameters:
      - name: company_id
        in: query
        description: Set the company where the change will be applied
        schema:
          type: string
      requestBody:
        required: true
        description: 'This body must contain two fields: `document_ids`, an array of strings representing the IDs of the documents from which tags should be removed, and `tags`, an array of objects where each object has an id (integer) or name (string) representing the tags to be removed. Each document in `document_ids` will have the specified `tags` removed.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTagsPayload'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MWAPIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MWAPIError'
      security:
      - JWT: []
  /v3/filter_sets:
    get:
      tags:
      - Listening Search Management
      summary: Get a list of all search filter sets
      operationId: list_filter_sets
      parameters:
      - name: company_id
        in: query
        description: Company which owns the given filter sets. If not specified your default company is used.
        required: false
        schema:
          type:

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/meltwater/refs/heads/main/openapi/meltwater-listening-search-management-api-openapi.yml