Signal AI Risk Events API

openapi: 3.2.0
info:
  title: Signal AI Risk Events 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: Risk Events
paths:
  /risk-events-search:
    post:
      operationId: risk-events-search
      security:
      - OAuth2:
        - risk-events
      tags:
      - Risk Events
      summary: Risk Events Search
      description: 'With our risk events search you can find significant events that impact business risk, extracted from our dataset of global news.


        Events are derived from news content and clustered on a daily basis. Each event instance is labelled according to the [Risk Event Definition][] it matched. It also includes information about the entities that instigated the event ("actors"), and those directly impacted ("targets").


        ### Search query criteria


        Construct a query to find events of interest by specifying matching criteria. The matching criteria are expressed in a `where` clause of the request body (see below). This works in a similar way to [Content Search][], however there is a more limited set of criteria and `exclude` clauses are not supported.


        The criteria available are:


        - the entities that were involved in the event, either as actors or targets

        - the event definitions

        - a date range of when the event was first reported


        The returned data will be paginated, with a maximum of 100 results per page depending on the requested `size` paramater. For more information see the [Pagination][] docs.


        ### Risk event metadata returned


        - unique event ID

        - the definition the event matched

        - the date the event was first reported

        - the date we first detected the event (normally the same as first reported)

        - the entities who were the "actors" in the event i.e. those that instigated or caused the event

        - the entities who were the "targets" of the event i.e. those who were directly impacted by the event

        - a list of documents that mentioned the event - id, headline and link will be provided, additional metadata can be retrieved using the [Get Document][] endpoint


        [Risk Event Definition]: #tag/Risk-Events/operation/risk-events-definitions

        [Get Document]: #tag/Content-Search/operation/get-document

        [Content Search]: #tag/Content-Search

        [Pagination]: #section/Pagination'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskEventSearchQuery'
      responses:
        '200':
          description: Returns a list of events matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskEventSearchResponse'
  /risk-events-definitions:
    get:
      operationId: risk-events-definitions
      security:
      - OAuth2:
        - risk-events
      tags:
      - Risk Events
      summary: Risk Event Definitions
      description: 'Our Risk Event Definitions represent a specific classification that we apply to news to extract events. Each definition is intended to describe a specific kind of concrete event that might happen. The goal is to find objective evidence of actions happening in the world, and avoid general discussion and speculation.


        Event definitions can be used for both filtering [Risk Events][] and computing [Risk Scores][].


        [Risk Events]: #tag/Risk-Events/operation/risk-events-search

        [Risk Scores]: #tag/Risk-Events/operation/risk-events-scores'
      responses:
        '200':
          description: Returns a list of available event definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskEventDefinitionResponse'
  /risk-events-scores:
    post:
      operationId: risk-events-scores
      security:
      - OAuth2:
        - risk-events
      tags:
      - Risk Events
      summary: Risk Events Scores
      description: 'Our risk scoring methodology provides an indication of how exposed a company may be to a specific risk. It does this by looking at the frequency of particular types of events, and how prominent this type of event is in the news media.


        ### Scoring query criteria


        Scoring is based on selecting events for a date range and a "cohort" of entities with a `where` clause, then applying scoring options with a `score-by` clause.


        The `where` clause is a subset of what is available in [Risk Events Search][]. It requires entities and a date range. The entities that make up this cohort represent a benchmark for scoring against.


        The `score-by` clause has two optional properties:


        - the entities to score, which should be a subset of the entities that made up the cohort defined in the `where`

        - the risk "pillars" which group different event definitions into arbitrary buckets


        The default behaviour without either of these options is to return a score for every available [Risk Event Definition][]. This tells you the overall risk score for the cohort.


        With the entities option set, a score is returned for every combination of Event Definition and the entities provided. This tells you the risk score for each entity.


        With the pillars option set, rather than getting a score for each event definition you will get a score for that group of event definitions. This allows organising the event definitions into arbitrary buckets to support different kinds of risk framework. When combined with the entities option a score is returned for each combination of entity and pillar.


        ### Score data returned


        The score data will include:


        - a name for each data point, which is either the pillar name provided, or the event definition name if pillars were not used

        - a list of the relevant event definitions, either from the pillar, or a list of one event definition if pillars were not used

        - optionally an entity, if entities were provided

        - the count of documents

        - the count of event instances

        - a number from 1 to 5 which represents the "likelihood" of the event based on previous frequency

        - a number from 1 to 5 which represents the "impact" of the event based on media prominence both absolutely and relatively to the cohort

        - the score, which is likelihood multiplied by impact, so always a number from 1 to 25


        [Risk Events Search]: #tag/Risk-Events/operation/risk-events-search

        [Risk Event Definition]: #tag/Risk-Events/operation/risk-events-definitions'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskEventScoreQuery'
      responses:
        '200':
          description: Returns a list of events matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskEventScoreResponse'
components:
  schemas:
    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
    RiskEventDefinitionResponse:
      type: object
      required:
      - event-definitions
      additionalProperties: false
      properties:
        event-definitions:
          type: array
          items:
            $ref: '#/components/schemas/RiskEventDefinition'
    Entity:
      type: object
      required:
      - id
      - name
      - type
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        type:
          $ref: '#/components/schemas/EntityType'
        name:
          type: string
    RiskEvent:
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
          description: ID of the event
        title:
          type: string
          description: A short description of the event
        event-definition:
          $ref: '#/components/schemas/RiskEventDefinition'
        first-reported:
          $ref: '#/components/schemas/Date'
          description: Date the event was first reported in the news
        first-detected:
          $ref: '#/components/schemas/Date'
          description: Date the event was first detected by AIQ
        actors:
          items:
            $ref: '#/components/schemas/Entity'
          type: array
          description: The entities that instigated the event
        targets:
          items:
            $ref: '#/components/schemas/Entity'
          type: array
          description: The entities that were impacted by the event
        documents:
          items:
            $ref: '#/components/schemas/RiskEventDocument'
          type: array
          description: 'The IDs and headlines from up to 3 articles mentioning the event.


            Further details can be obtained from the Document API'
      required:
      - id
      - title
      - event-definition
      - first-reported
      - first-detected
      - actors
      - targets
      - documents
      type: object
      additionalProperties: false
    RiskEventSearchResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/RiskEvent'
          type: array
          maxItems: 100
        next-cursor:
          type: string
          description: Use the `next-cursor` field from a previous response to get the next page of results (see [Pagination](#section/Pagination))
      required:
      - events
      type: object
      additionalProperties: false
    RiskPillar:
      properties:
        name:
          type: string
        event-definition-ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceId'
      type: object
      required:
      - name
      - event-definition-ids
      additionalProperties: false
    RiskEventScoreQuery:
      type: object
      required:
      - where
      - score-by
      additionalProperties: false
      properties:
        where:
          $ref: '#/components/schemas/RiskScoreMatch'
        score-by:
          $ref: '#/components/schemas/RiskScoreBy'
    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'
    RiskScoreMatch:
      type: object
      additionalProperties: false
      required:
      - entities
      - first-reported-at
      properties:
        first-reported-at:
          $ref: '#/components/schemas/DateRangeMatch'
        entities:
          $ref: '#/components/schemas/RiskEventEntitiesMatch'
    RiskScore:
      properties:
        name:
          type: string
        event-definitions:
          type: array
          items:
            $ref: '#/components/schemas/RiskEventDefinition'
        entity:
          $ref: '#/components/schemas/Entity'
        document-count:
          type: number
        event-count:
          type: number
        likelihood:
          type: number
          minimum: 1
          maximum: 5
        impact:
          type: number
          minimum: 1
          maximum: 5
        score:
          type: number
          minimum: 1
          maximum: 25
      required:
      - name
      - event-definitions
      - document-count
      - event-count
      - likelihood
      - impact
      - score
      type: object
      additionalProperties: false
    RiskEventMatch:
      type: object
      additionalProperties: false
      properties:
        first-reported-at:
          $ref: '#/components/schemas/DateRangeMatch'
        entities:
          $ref: '#/components/schemas/RiskEventEntitiesMatch'
        event-definitions:
          $ref: '#/components/schemas/RiskEventDefinitionsMatch'
    RiskEventSearchQuery:
      type: object
      required:
      - where
      additionalProperties: false
      properties:
        where:
          $ref: '#/components/schemas/RiskEventMatch'
        size:
          type: number
          minimum: 1
          maximum: 100
          default: 20
          description: Set the number of events to return per page
        from-cursor:
          type: string
          description: Use the `next-cursor` field from a previous response to get the next page of results (see [Pagination](#section/Pagination))
    RiskEventEntitiesMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                type: array
                minItems: 1
                maxItems: 20
    EntityType:
      type: string
      enum:
      - person
      - organisation
      - location
      - substance
      - disease
      - product
      - regulation
    RiskEventDefinitionsMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                type: array
                minItems: 1
                maxItems: 200
    RiskEventScoreResponse:
      type: object
      required:
      - scores
      additionalProperties: false
      properties:
        scores:
          type: array
          items:
            $ref: '#/components/schemas/RiskScore'
    DateRangeMatch:
      type: object
      properties:
        gte:
          $ref: '#/components/schemas/Date'
        lte:
          $ref: '#/components/schemas/Date'
      additionalProperties: false
      minProperties: 1
    RiskEventDefinition:
      type: object
      required:
      - id
      - name
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    RiskEventDocument:
      type: object
      required:
      - id
      - title
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        title:
          type: string
        signal-url:
          type: string
    AnyResourceIds:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          $ref: '#/components/schemas/ResourceIds'
    RiskScoreBy:
      properties:
        entity-ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceId'
        pillars:
          type: array
          items:
            $ref: '#/components/schemas/RiskPillar'
      type: object
      additionalProperties: false
  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