openapi: 3.0.1
info:
  title: Context Check API
  summary: >-
    <b>An API for checking the context of inputs and managing those
    contextChecks</b>
  description: >-
    This API endpoint evaluates the context of a claim, determining its
    accuracy, relevance, and trustworthiness. It leverages advanced AI to
    analyze the claim in relation to publicly available data, sources, and
    narratives to identify potential misinformation or disinformation.


    You can try these out in your browser with the [OpenAPI
    Spec](https://api.blackbird.ai/compass/openapi/#/ContextChecks). Be sure to
    hit "Authorize 🔓" and enter your credentials first.
servers:
  - url: https://api.blackbird.ai/compass
x-hideTryItPanel: false
x-codeSamples: true
paths:
  /contextChecks:
    post:
      summary: Create a new context check
      description: >-
        Creates a new contextCheck. The resource isn't fully created immediately
        and you'll want to poll the `/contextChecks/{id}` GET for the result.
      operationId: createContextCheck
      parameters:
        - name: cache-control
          in: header
          required: false
          description: >-
            Whether to bypass the cached response. Requires permission to bypass
            the cache.
          schema:
            type: string
            enum:
              - no-cache
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContextCheckRequest'
      responses:
        '200':
          description: ContextCheck accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingContextCheck'
    get:
      summary: Gets all the contextChecks the caller has submitted
      operationId: getContextChecks
      parameters:
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Filter contextChecks created after this date (inclusive with
            ascending sort order, exlusive with descending sort order)
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Filter contextChecks created before this date (exclusive with
            ascending sort order, inclusive with descending sort order)
        - name: limit
          in: query
          required: false
          schema:
            type: number
            default: 25
            maximum: 1000
          description: The number of contextChecks to return.
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: The direction to sort contextChecks by created_at
      responses:
        '200':
          description: ContextChecks found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextChecksQueryResponse'
  /contextChecks/{id}:
    get:
      summary: Get input and context
      description: >-
        Retrieves the contextCheck with the input and the generated context
        around it
      operationId: getContextCheck
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the contextCheck to retrieve.
      responses:
        '200':
          description: ContextCheck found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextCheck'
        '404':
          description: ContextCheck not found
components:
  securitySchemes:
    oAuth2Password:
      type: oauth2
      flows:
        password:
          tokenUrl: /compass/token
          scopes: {}
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://blackbird-ai.auth.us-west-2.amazoncognito.com/oauth2/token
          scopes: {}
  schemas:
    BaseContextCheck:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - status
        - input
      properties:
        id:
          type: string
          description: The ID of the contextCheck
        created_at:
          type: string
          format: date-time
          description: The datetime the contextCheck was created
        updated_at:
          type: string
          format: date-time
          description: >-
            The datetime the contextCheck was last updated. Will just be the
            created date or completed date
        input:
          type: string
          description: The contextCheck to generate context for
        status:
          type: string
          description: The status of the contextCheck context generation
    ProcessingContextCheck:
      allOf:
        - $ref: '#/components/schemas/BaseContextCheck'
        - type: object
          properties:
            status:
              type: string
              enum:
                - processing
          example:
            id: '8115'
            created_at: '2024-10-10T15:20:33.307Z'
            updated_at: '2024-10-10T15:20:33.307Z'
            status: processing
            input: Who is older, Biden or Trump?
    ContextSource:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: The link to the source content
        title:
          type: string
          description: The title of the page content of the source
        content:
          type: string
          description: The entire textual page content of the source used
        favicon:
          type: string
          description: An icon for the source
    ContextCheckEnrichment:
      type: object
      required:
        - link
        - input_type
        - authors
        - links
      properties:
        link:
          type: string
          description: The link that was hydrated
        input_type:
          oneOf:
            - type: string
              enum:
                - twitter
                - youtube
                - tiktok
                - instagram
                - reddit
                - facebook
                - image
                - video
                - webpage
              description: >-
                The type of data that was hydrated from the provided `link`.
                Note that there will be more values in the future and you should
                not consider a value outside the known enumeration as a breaking
                change
            - type: string
        created_at:
          type: string
          format: date-time
          description: The date-time the linked data was published to the internet
        title:
          type: string
          description: A title for the hydrated content if there is one
        text:
          type: string
          description: The full text of the hydrated content
        image:
          type: string
          description: >-
            The link to the image that was hydrated, if one was hydrated. May be
            the original link provided or an image linked from it
        video:
          type: string
          description: >-
            The link to the video that was hydrated, if one was hydrated.  May
            be the original link provided or a url linked from it
        authors:
          type: array
          description: The author(s) of the hydrated content
          items:
            type: object
            required:
              - name
            properties:
              name:
                type: string
                description: The author of the content.
              profile_image:
                type: string
                description: An image link for the author of the content
        links:
          type: array
          description: Any links to more data from the original content that was hydrated
          items:
            type: object
            required:
              - href
            properties:
              href:
                type: string
                description: The link to the extra data
              text:
                type: string
                description: Textual representation of what is at the link
    Context:
      type: object
      required:
        - created_at
        - response
        - sources
      properties:
        created_at:
          type: string
          format: date-time
          description: The datetime the context was created
        summary:
          type: string
          description: The summarized analysis about the context returned in the response
        response:
          type: string
          description: The generated context about the contextCheck
        sources:
          type: array
          description: The sources used to generate the contextCheck
          items:
            $ref: '#/components/schemas/ContextSource'
        enrichment:
          allOf:
            - description: Any hydration performed on the input while building the context
            - $ref: '#/components/schemas/ContextCheckEnrichment'
        label:
          type: string
          description: >-
            Classication label of compass risk. Label can be ['Safe', 'Caution',
            'Warning']
    SuccessfulContextCheck:
      allOf:
        - $ref: '#/components/schemas/BaseContextCheck'
        - type: object
          required:
            - context
          properties:
            status:
              type: string
              enum:
                - success
            context:
              $ref: '#/components/schemas/Context'
    FailureContextCheck:
      allOf:
        - $ref: '#/components/schemas/BaseContextCheck'
        - type: object
          required:
            - error
          properties:
            status:
              type: string
              enum:
                - failed
            error:
              type: string
              example: There was an error processing your contextCheck.
    ContextCheck:
      oneOf:
        - $ref: '#/components/schemas/ProcessingContextCheck'
        - $ref: '#/components/schemas/SuccessfulContextCheck'
        - $ref: '#/components/schemas/FailureContextCheck'
      discriminator:
        propertyName: status
        mapping:
          processing: '#/components/schemas/ProcessingContextCheck'
          success: '#/components/schemas/SuccessfulContextCheck'
          failed: '#/components/schemas/FailureContextCheck'
    ContextChecksQueryResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContextCheck'
    CreateContextCheckRequest:
      type: object
      required:
        - input
      properties:
        input:
          type: string
          description: The input to generate context for
        modelVersion:
          type: string
          enum:
            - '1.0'
            - '2.0'
          description: >-
            The version of the model to use to generate the context. Defaults to
            "1.0"
      example:
        input: Are US troops fighting in Ukraine?
security:
  - clientCredentials: []
  - oAuth2Password: []
