{
  "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.\n\nYou 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,
            "allowReserved": true,
            "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,
            "allowReserved": true,
            "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,
            "allowReserved": true,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            },
            "description": "The direction to sort contextChecks by created_at"
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "allowReserved": true,
            "schema": {
              "type": "string"
            },
            "description": "Filters context checks with their corresponding indexOn value if the writer set one."
          }
        ],
        "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": "https://api.blackbird.ai/compass/token",
            "scopes": {}
          }
        }
      },
      "clientCredentials": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.blackbird.ai/auth/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"
          },
          "lang": {
            "type": "string",
            "description": "The inferred language of the hydrated content, if determined"
          },
          "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"
        ],
        "additionalProperties": false,
        "properties": {
          "input": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10000,
            "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\""
          },
          "tags": {
            "type": "object",
            "description": "Any metadata tags to apply to the context check. Not used by Compass, but can be useful for associating caller metadata.",
            "patternProperties": {
              "^[a-zA-Z0-9_]+$": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100
              }
            },
            "maxProperties": 10,
            "propertyNames": {
              "type": "string",
              "maxLength": 100
            }
          },
          "indexOn": {
            "type": "string",
            "description": "An additional field to index the context check on. Can be filtered in the GET /contextChecks endpoint with the filter query parameter",
            "maxLength": 100
          }
        },
        "example": {
          "input": "Are US troops fighting in Ukraine?"
        }
      }
    }
  },
  "security": [
    {
      "clientCredentials": []
    },
    {
      "oAuth2Password": []
    }
  ]
}