Signal AI Content Search API

openapi: 3.2.0
info:
  title: Signal AI Content Search API
  description: '# Overview


    The Signal AI API is an HTTP+JSON API offering programmatic access to Signal AI''s decision augmentation platform.'
  version: v1.3
servers:
- url: https://api.signal-ai.com
security:
- OAuth2:
  - default
tags:
- name: Content Search
paths:
  /search:
    post:
      operationId: search-documents
      security:
      - OAuth2:
        - search
      tags:
      - Content Search
      summary: Smart content search powered by Signal AI's trained concepts
      description: 'With our smart content search, you can find documents of interest to you from Signal AI''s live indexed content (the world''s largest dataset of real-time, global news and regulatory information). You are able to search over the last 15 months of indexed content.


        A search response will contain a page of `documents` metadata matching the search query.


        ### Search query criteria

        Construct a query to find documents of your interest, by specifying some matching criteria. In particular, you can use the `where`, and the `exclude` clauses in the request body (see below).

        The `where` clause defines criteria that the documents returned should match, whereas the `exclude` clause is the opposite and defines criteria that documents must not match (i.e. it filters out documents that match those criteria)


        The criteria that can be used for matching documents in the query include:

        * the entities mentioned in the document (up to 200 per query)

        * the topics that the document relates to (up to 100 per query)

        * the publication sources or countries, regions or subregions of publication (up to 500 sources per query)

        * the IPTC categories that the document relates to

        * the publication date & time

        * the language of the document

        * the media type of the document (online or print)

        * the document story ID (up to 200 per query)


        Note that for the `exclude` clause, only the the first three criteria can be used (entities, topics and sources)


        ### Documents metadata returned

        The metadata returned for each document matching the query includes:

        * unique document ID

        * story ID

        * document title

        * native language document title (for non-english content)

        * Signal url (for online content only)

        * publication source and location (country, subregion & region)

        * publication date & time

        * the media type of the document (e.g. online)

        * the language of the document

        * the full list of topics that the document pertains to

        * the full list of IPTC categories that the document pertains to

        * the full list of entities mentioned in the document, with the content position, saliency and associated sentiment label for each mention


        ### Sorting

        Documents can be sorted by:

        * `published-at` - publication date (default)

        * `score` - relevance score


        The direction of sorting can be specified as:

        * `desc` - descending (default)

        * `asc` - ascending


        ### Pagination limitations


        ⚠️ **Pagination is not supported when sorting results by relevance score**


        You can only get one page of documents (up to the maximum page size of 500), and the response will not include a `next-cursor` field.


        ### Story deduplication

        Signal AI identifies syndicated articles pertaining to the same story and assigns them the same `story-id`. This can be useful for the purpose of deduplicating articles if you are interested in unique stories only. Because the publication of syndicated articles on the same story can span several hours or sometimes even days, there is no guarantee that all articles on the same story will be listed contiguously in the API response.


        ### Keyword limitations

        In order to use the inclusion keywords, you must include **at least** one of `entities`, `source` or `topics` in the `where` clause of the request.


        There is a **50 word** limit on keywords across inclusion and exclusion. A keyword can be made up of sevaral words, i.e. the keyword `Big Tech` would count as **2 words**.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentSearchQuery'
            examples:
              entity-search:
                $ref: '#/components/examples/document-search-by-entity'
              source-country-search:
                $ref: '#/components/examples/document-search-by-country-and-entity'
              entities-source-search:
                $ref: '#/components/examples/document-search-by-source-and-entities'
              entity-topics-search:
                $ref: '#/components/examples/document-search-by-entity-and-topics'
              sort-by-relevance:
                $ref: '#/components/examples/document-search-sort-by-relevance'
      responses:
        '200':
          description: Returns a list of documents matching the search query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSearchResponse'
  /documents/{id}:
    get:
      operationId: get-document
      tags:
      - Content Search
      summary: Get a document by id
      parameters:
      - name: id
        required: true
        in: path
        schema:
          $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Returns the document for this id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
components:
  schemas:
    ResourceIdsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsResourceId'
      - $ref: '#/components/schemas/AnyResourceIds'
      - $ref: '#/components/schemas/AllResourceIds'
    DocumentMatch:
      type: object
      additionalProperties: false
      properties:
        story-id:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyResourceIdsMatch'
          - properties:
              any:
                maxItems: 200
        entities:
          $ref: '#/components/schemas/DocumentEntitiesMatch'
        published-at:
          $ref: '#/components/schemas/DateTimeRangeMatch'
        source:
          $ref: '#/components/schemas/SourceMatch'
        keywords:
          $ref: '#/components/schemas/DocumentKeywordsMatch'
        topics:
          $ref: '#/components/schemas/DocumentTopicsMatch'
        categories:
          $ref: '#/components/schemas/CategoriesMatch'
        language:
          $ref: '#/components/schemas/LanguageMatch'
        media-type:
          $ref: '#/components/schemas/MediaTypeMatch'
    SourceExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 500
    ResourceId:
      type: string
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: bcd2d868-ed38-4382-b94a-622a30fc3215
    Entity:
      type: object
      required:
      - id
      - name
      - type
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        type:
          $ref: '#/components/schemas/EntityType'
        name:
          type: string
    AllTerms:
      type: object
      additionalProperties: false
      required:
      - all
      properties:
        all:
          type: array
          items:
            type: string
    MediaType:
      type: string
      enum:
      - online
      - print
    AnyMediaType:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          type: array
          items:
            $ref: '#/components/schemas/MediaType'
    EqualsOrAnyOrAllTermsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsTerm'
      - $ref: '#/components/schemas/AnyTerms'
      - $ref: '#/components/schemas/AllTerms'
    DateTime:
      type: string
      format: date-time
      description: "A date and time based on the IETF RFC 3339 format (e.g.\n     `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC,\n     `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default."
      example: '2023-01-01T13:37:00'
    EqualsOrAnyTermsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsTerm'
      - $ref: '#/components/schemas/AnyTerms'
    DocumentSearchResponse:
      type: object
      required:
      - stats
      - documents
      properties:
        stats:
          $ref: '#/components/schemas/SearchStats'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        next-cursor:
          $ref: '#/components/schemas/Base64String'
    RegulatoryDocumentType:
      type: string
      enum:
      - alert
      - announcement
      - bill
      - circular
      - consultation paper
      - decision
      - enforcement
      - general
      - guidance
      - hearing
      - interview
      - judgement
      - legislation
      - letter
      - opinion
      - parliamentary commentary
      - policy paper
      - press release
      - publication
      - resolution
      - sanctions
      - speech
      - statement
      - tender
      - transcript
      - transparency
      - warning
      - other
      description: <span class="beta-tag"></span> Regulatory document categorisation
    DocumentTopicsMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                maxItems: 100
              all:
                maxItems: 100
    Mention:
      type: object
      required:
      - position
      additionalProperties: false
      properties:
        position:
          type: string
          enum:
          - content
          - summary
          - title
          - quote
        sentiment:
          $ref: '#/components/schemas/SentimentLabel'
    SentimentLabel:
      type: string
      enum:
      - positive
      - negative
      - neutral
    AllResourceIds:
      type: object
      additionalProperties: false
      required:
      - all
      properties:
        all:
          $ref: '#/components/schemas/ResourceIds'
    DocumentPosition:
      type: string
      enum:
      - title
      - title or summary
      - full content
      - quotes only
    ExcludeClause:
      type: object
      additionalProperties: false
      properties:
        entities:
          $ref: '#/components/schemas/EntitiesExclusion'
        topics:
          $ref: '#/components/schemas/TopicsExclusion'
        source:
          oneOf:
          - $ref: '#/components/schemas/SourceExclusion'
          - $ref: '#/components/schemas/CountryExclusion'
        keywords:
          $ref: '#/components/schemas/KeywordsExclusion'
    Document:
      type: object
      required:
      - id
      - title
      - published-at
      - source
      - media-type
      - topics
      - entities
      additionalProperties: false
      properties:
        story-id:
          $ref: '#/components/schemas/ResourceId'
        signal-url:
          type: string
        regulatory-document:
          $ref: '#/components/schemas/RegulatoryDocumentType'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityWithMentions'
        published-at:
          type: string
          format: date-time
        source:
          $ref: '#/components/schemas/Source'
        title:
          type: string
        topics:
          type: array
          items:
            $ref: '#/components/schemas/PartialTopic'
        categories:
          type: object
          deprecated: true
          properties:
            iptc-media-topics:
              type: array
              items:
                $ref: '#/components/schemas/Category'
        language:
          type: string
        id:
          $ref: '#/components/schemas/ResourceId'
        native-title:
          type: string
          description: Document title in its native language (for non english content)
        media-type:
          $ref: '#/components/schemas/MediaType'
    TopicsExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 50
    Date:
      type: string
      format: date
      description: "A date based on the IETF RFC 3339 format (e.g. `2023-01-01`).\n    Note that a day is the span of time between 00:00:00 and 23:59:59 based on\n    the UTC timezone. You may prefer using the `date-time` option to match days\n    in a different timezone."
      example: '2023-01-01'
    ResourceIds:
      type: array
      items:
        $ref: '#/components/schemas/ResourceId'
    SortField:
      type: string
      enum:
      - published-at
      - score
    EqualsOrAnyResourceIdsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsResourceId'
      - $ref: '#/components/schemas/AnyResourceIds'
    DocumentKeywordsMatch:
      type: object
      required:
      - value
      properties:
        value:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyOrAllTermsMatch'
          - description: There is a 50 word limit for keywords across inclusion and exclusion. See the section **Keyword limitations** above for more details.
        mentions:
          $ref: '#/components/schemas/MentionPositionMatch'
      description: Note that to use inclusion keywords, you will also need to include one of `entities`, `sources` or `topics` in your `where` clause.
    MentionPositionMatch:
      type: object
      additionalProperties: false
      required:
      - position
      properties:
        position:
          $ref: '#/components/schemas/DocumentPosition'
      description: Note that mentions found in `summary` or `quotation` are a subset of the mentions found in the `full content`.
    EqualsResourceId:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          $ref: '#/components/schemas/ResourceId'
    LanguageMatch:
      oneOf:
      - type: object
        additionalProperties: false
        required:
        - eq
        properties:
          eq:
            type: string
            description: Language (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
      - type: object
        name: AnyLanguage
        additionalProperties: false
        required:
        - any
        properties:
          any:
            type: array
            items:
              type: string
            description: A list of languages (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
    DateOrDateTime:
      oneOf:
      - $ref: '#/components/schemas/Date'
      - $ref: '#/components/schemas/DateTime'
    Category:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        name:
          type: string
    DocumentEntitiesMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                type: array
                maxItems: 200
              all:
                type: array
                maxItems: 200
        salient-only:
          type: boolean
          description: Only return documents for which these entities are salient
        mentions:
          $ref: '#/components/schemas/MentionPositionMatch'
    DocumentResponse:
      type: object
      required:
      - document
      properties:
        document:
          $ref: '#/components/schemas/Document'
    Source:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        name:
          type: string
        country:
          type: string
        subregion:
          type: string
        region:
          type: string
      example:
        id: 61e158b0-f3a4-468c-9857-03841aa90ef4
        name: The Newspaper
        country: United Kingdom
        subregion: Northern Europe
        region: Europe
    EntityWithMentions:
      type: object
      allOf:
      - $ref: '#/components/schemas/Entity'
      - required:
        - sentiment
        - mentions
        properties:
          sentiment:
            $ref: '#/components/schemas/SentimentLabel'
          salient:
            type: boolean
            description: Indicates if this entity is truly central to the content of the document
          salience-rank:
            type: integer
            minimum: 1
            description: Indicates how close this entity is to the topic of discussion in the article, in relation to other entities mentioned. A lower rank means a higher salience.
          mentions:
            type: array
            items:
              $ref: '#/components/schemas/Mention'
            description: The positions of the entity in the document
    DateTimeRangeMatch:
      type: object
      properties:
        gt:
          $ref: '#/components/schemas/DateOrDateTime'
        gte:
          $ref: '#/components/schemas/DateOrDateTime'
        lt:
          $ref: '#/components/schemas/DateOrDateTime'
        lte:
          $ref: '#/components/schemas/DateOrDateTime'
      additionalProperties: false
      minProperties: 1
      dependentSchemas:
        gt:
          not:
            required:
            - gte
        gte:
          not:
            required:
            - gt
        lt:
          not:
            required:
            - lte
        lte:
          not:
            required:
            - lt
    PartialTopic:
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        name:
          type: string
    EntitiesExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 100
    EntityType:
      type: string
      enum:
      - person
      - organisation
      - location
      - substance
      - disease
      - product
      - regulation
    SearchStats:
      type: object
      required:
      - total
      properties:
        total:
          type: integer
          description: Approximate total number of documents matching this search
    EqualsMediaType:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          $ref: '#/components/schemas/MediaType'
    MediaTypeMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsMediaType'
      - $ref: '#/components/schemas/AnyMediaType'
    AnyTerms:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          type: array
          items:
            type: string
    CountryExclusion:
      type: object
      additionalProperties: false
      required:
      - country
      properties:
        country:
          $ref: '#/components/schemas/AnyTerms'
    SortClause:
      type: array
      prefixItems:
      - $ref: '#/components/schemas/SortField'
      - $ref: '#/components/schemas/SortOrder'
      items: false
    KeywordsExclusion:
      type: object
      additionalProperties: false
      required:
      - value
      properties:
        value:
          $ref: '#/components/schemas/AnyTerms'
    SortOrder:
      type: string
      enum:
      - asc
      - desc
    SourceMatch:
      type: object
      additionalProperties: false
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyResourceIdsMatch'
          - properties:
              any:
                maxItems: 500
        country:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
        region:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
        subregion:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
    EqualsTerm:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          type: string
    DocumentSearchQuery:
      type: object
      required:
      - where
      additionalProperties: false
      properties:
        where:
          $ref: '#/components/schemas/DocumentMatch'
        exclude:
          $ref: '#/components/schemas/ExcludeClause'
        size:
          type: integer
          default: 10
          minimum: 0
          maximum: 500
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SortClause'
          minItems: 1
          default:
          - - published-at
            - desc
          description: 'format: `[[SORT_FIELD, SORT_ORDER], ...]` where `SORT_FIELD` can be one of `"published-at"` or `"score"`, and `SORT_ORDER` one of `"asc"` or `"desc"`'
        from-cursor:
          $ref: '#/components/schemas/Base64String'
          description: Use the `next-cursor` field from a previous response to get the next page of results (see [Pagination](#section/Pagination))
    AnyResourceIds:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          $ref: '#/components/schemas/ResourceIds'
    CategoriesMatch:
      type: object
      deprecated: true
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                maxItems: 100
              all:
                maxItems: 100
    Base64String:
      type: string
      pattern: ^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$
      example: RjQ2RTRBQUEtQTNGRi00MEI3LUE1NEYtNTA0NEQxMjc5NkU3
  examples:
    document-search-by-entity-and-topics:
      summary: Search for an entity in relation to any one of a number of topics (title mentions only)
      value:
        where:
          entities:
            id:
              eq: 73159b73-e3db-4895-8e29-89ee8da59765
            mentions:
              position: title
          topics:
            id:
              any:
              - 4762733c-baa7-4a91-958f-fdbbd96972cb
              - 78a219a9-6997-4b9e-afa2-d8b94378ddea
              - 7a162a73-0062-4772-9dc0-252dd862dad0
        size: 100
    document-search-by-entity:
      summary: Search for documents mentioning an entity, published in a specific time range
      value:
        where:
          published-at:
            gte: '2021-03-01'
            lt: '2021-04-01'
          entities:
            id:
              eq: 1c7f436c-7d0b-4fdf-affb-aaebbac81ce5
    document-search-sort-by-relevance:
      summary: Sort results by relevance score in descending order
      value:
        where:
          entities:
            id:
              eq: 73159b73-e3db-4895-8e29-89ee8da59765
          topics:
            id:
              eq: 4762733c-baa7-4a91-958f-fdbbd96972cb
        sort:
        - - score
          - desc
    document-search-by-source-and-entities:
      summary: Search for multiple entities mentionned together in a given publication
      value:
        where:
          published-at:
            gte: '2021-03-01'
          source:
            id:
              eq: e2eaec02-08fb-4a8a-a4da-1c14ddf52bb2
          entities:
            id:
              all:
              - 11cab8df-4be1-470f-8f49-8f7f0863ec95
              - 73159b73-e3db-4895-8e29-89ee8da59765
    document-search-by-country-and-entity:
      summary: Search for documents mentioning an entity, published in a specific country
      value:
        where:
          published-at:
            gt: '2021-03-01T12:00:00Z'
          source:
            country:
              eq: United Kingdom
          entities:
            id:
              eq: 1c7f436c-7d0b-4fdf-affb-aaebbac81ce5
  securitySchemes:
    OAuth2:
      type: oauth2
      description: "To obtain the Bearer Token using the Client ID / Secret pair provided to you:\n\n```bash\ncurl -X POST \\\n  -d 'grant_type=client_credentials' \\\n  -d 'client_id=YOUR_CLIENT_ID' \\\n  -d 'client_secret=YOUR_CLIENT_SECRET' \\\n  https://api.signal-ai.com/auth/token\n```\n\nThis will return the following JSON response:\n\n```json\n{\n    \"access_token\": \"eyJhbGciOi…\",\n    \"expires_in\": 86400,\n    …\n}\n```\n\nYou must send the `access_token` from this response in the Authorization header when making requests to other API endpoints:\n\n```bash\ncurl -H \"Authorization: Bearer eyJhbGciOi…\" \\\n  https://api.signal-ai.com/…\n```\n\nAccess tokens will expire 24 hours from the time they were issued.\n"
      flows:
        clientCredentials:
          tokenUrl: https://api.signal-ai.com/auth/token
          scopes:
            default: Access to discovery endpoints
            search: Access to content search endpoint
            metrics: Access to content metrics endpoint
            affinity: Access to concept affinity endpoints
            events: Access to events endpoint
            risk-events: Access to risk events
            manage-organisation: Access to organisation administration endpoints
x-tagGroups:
- name: Concept Discovery
  tags:
  - Publication sources
  - Topics
  - Entities
  - Categories
- name: Search
  tags:
  - Content Search
- name: Metrics
  tags:
  - Content Metrics
- name: Affinity
  x-displayName: Affinity
  tags:
  - Affinity
- name: Events
  x-displayName: Events
  tags:
  - Events
- name: Risk (Alpha)
  tags:
  - Risk Events
- name: Organisation
  tags:
  - Organisation