API Reference
Introduction
This Orca AI API provides access to the same data also accessible through our HUNT web research tool.
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 base endpoint is https://api.orcaai.io/. 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. See ISO-3166 Country Codes
Section
A section is a classification of data proprietary to Orca AI. We use sections to organize our data catalog. Each section is identified by a unique ID and contains various attributes. Some of our APIs allow restricting by section.
Resources
POST /v0.3/huntActive
Description: Creates a paginated Orca AI Hunt report. Returns up to 50 results per page with pagination support.
Request Schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"query": {
"type": "string"
},
"nextToken": {
"type": "string",
"description": "Encrypted token for paginating to next set of results"
}
},
"required": ["query"],
"additionalProperties": false
}Response Schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"query": {
"type": "string"
},
"nextToken": {
"type": "string",
"description": "Encrypted token for next page, null if no more results"
},
"huntDocuments": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"datasetId": {
"type": "string"
},
"id": {
"type": "string"
},
"names": {
"type": "array",
"items": {
"type": "string"
}
},
"primaryName": {
"type": "string"
},
"rawData": {
"type": "string"
},
"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",
"values",
"dataset",
"tabularData"
]
}
}
},
"required": [
"query",
"nextToken",
"huntDocuments"
],
"additionalProperties": false
}POST /v0.2/huntActive
Description: Creates a paginated Orca AI Hunt report. Returns up to 100 results per page with pagination support.
Note: v0.2 uses the same schema as v0.3 but without the enhanced filtering capabilities.
POST /v0.1/huntLegacy
Description: Creates a new Orca AI Hunt report. Note: Returns all results up to 50,000 records.
Request Schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"query": {
"type": "string"
}
},
"required": ["query"],
"additionalProperties": false
}GET /data/authorities
Description: Retrieves a list of all available authorities (countries, organizations, and quasi-governmental entities) in the ORCA AI dataset.
Response Format: Returns an array of authority objects with IS-3166 codes and descriptions.
Example Response:
[
{
"code": "AD",
"name": "Andorra"
},
{
"code": "ADB",
"name": "Asian Development Bank"
},
{
"code": "AE",
"name": "United Arab Emirates"
},
{
"code": "AF",
"name": "Afghanistan"
},
{
"code": "AFDB",
"name": "African Development Bank"
}
...
]GET /data/sections
Description: Retrieves a list of all available data sections and categories within the ORCA AI dataset suitable for filtering search results.
Response Format: Returns an array of section objects with names and descriptions.
Example Response:
{
"sections": [
{
"id": 0
"name": "[Section Description]",
"specificLanguage": "description of section"
}
...
]
}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://api.orcaai.io/v0.1/hunt" \
--header "x-api-key: [API-Key]" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "John Smith"
}'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. See Versions for details.
The v0.3 form of the POST request to execute a HUNT report:
https://api.orcaai.io/v0.3/hunt
Usage Examples
v0.2 Examples (Paginated)
Example 1: First Page Request
curl --location --request POST "https://api.orcaai.io/v0.2/hunt" \
--header "x-api-key: your-api-key-here" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "Vladimir Putin"
}'Example 2: Subsequent Page Request
curl --location --request POST "https://api.orcaai.io/v0.2/hunt" \
--header "x-api-key: your-api-key-here" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "Vladimir Putin",
"nextToken": "YWVzZW5jcnlwdGVkdG9rZW5oZXJlMTIzNDU2"
}'Example 3: v0.2 Response
{
"query": "Vladimir Putin",
"nextToken": "ZW5jcnlwdGVkbmV4dHBhZ2V0b2tlbjEyMzQ1Ng==",
"huntDocuments": [
{
"datasetId": "example-dataset-001",
"id": "record-12345",
"names": ["Vladimir Putin", "Владимир Путин"],
"primaryName": "Vladimir Putin",
"rawData": "Putin, Vladimir Vladimirovich...",
"values": ["President", "Russian Federation"],
"dataset": {
"authorities": ["RU"],
"section": "Government Officials",
"exactListName": "Russian Government Directory",
"implementingOrganization": "Government of Russian Federation"
},
"tabularData": {
"headers": ["Name", "Position", "Country"],
"fields": ["Vladimir Putin", "President", "Russia"]
}
}
]
}Error / HTTP Response Codes
Error Response Format
{
"error": {
"code": 400,
"message": "Invalid request format",
"details": "The 'query' field is required and cannot be empty"
}
}