API Reference v0.1

Introduction

This documentation describes the Orca API, which provides the same data also accessible through our HUNT web research tool. The API is designed to be easy to use and to provide a simple way to access our data.

To use the Orca AI API, you must have an API key which is provided to API account users. Usage limits are determined by your account type and plan.

Getting Started

The endpoint is https://api.orcaai.io/v0.1/. We currently only support HTTPS to maintain security.

The API is RESTful and uses standard HTTP response codes to indicate API errors. JSON is returned in all responses from the API, including errors.

Common Attributes & Objects

The Orca AI API uses several common attributes and objects. These provide additional information and context about the data returned by the API.

Authority

An authority is the primary nation state, multinational organization, or quasi-governmental organization which originated the record. These conform to ISO-3166 Country (e.g., "US", "CA", "JP"), ISO-3166 Exceptional (e.g., "EU", "UN"), or Custom Authority (e.g., "ADB", "FATF", "ICC") codes.

Resources

POST /v0.1/hunt

Description: Creates a new Orca AI Hunt report.

Request Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    }
  },
  "required": ["query"],
  "additionalProperties": false
}

Response Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "huntDocuments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "datasetId": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "primaryName": {
            "type": "string"
          },
          "rawData": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "dataset": {
            "type": "object",
            "properties": {
              "authorities": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "section": {
                "type": "string"
              },
              "exactListName": {
                "type": "string"
              },
              "implementingOrganization": {
                "type": "string"
              }
            },
            "required": [
              "authorities",
              "section",
              "exactListName",
              "implementingOrganization"
            ]
          },
          "tabularData": {
            "type": "object",
            "properties": {
              "headers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "headers",
              "fields"
            ]
          }
        },
        "required": [
          "datasetId",
          "id",
          "names",
          "primaryName",
          "rawData",
          "timestamp",
          "values",
          "dataset",
          "tabularData"
        ]
      }
    }
  },
  "required": [
    "query",
    "huntDocuments"
  ],
  "additionalProperties": false
}

Usage Limits

API usage limits depend on your account type and plan.

API Accounts

An API key is required to use the Orca AI API and will be provided to you with your account. API Keys match the pattern [0-9A-Za-z]{40}.

Authentication

Authentication is by passing the API key as the x-api-key header with each request. Please keep your API key safe and always send requests to the HTTPS endpoint.

Example request (replace [API-Key] with your key):

curl --location --request POST "https://huntapi.orcaai.io/v0.1/hunt" --header "x-api-key: [API-Key]"

Stability & Versioning

The Orca AI API uses a versioning system. When we introduce changes, we change the version number so that queries to the previous version will still behave the same way. If you supply a version number, that version will be used (if supported). If no version is supplied, the current version will be used. See Versions for details.

The v0.1 form of the POST request to execute a HUNT report:

https://api.orcaai.io/v0.1/hunt

The unversioned form is:

https://api.orcaai.io/hunt

Error / HTTP Response Codes

• 200 OK: Success!
• 304 Not Modified: No new data to return.
• 400 Bad Request: The request was invalid.
• 403 Forbidden: Refused (rate limiting or invalid API key).
• 404 Not Found: The URI or resource does not exist.
• 500 Internal Server Error: Something is broken.
• 502 Bad Gateway: Orca AI is down or being upgraded.
• 503 Service Unavailable: Orca AI servers are overloaded.