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 base endpoint is https://api.orcaai.io/ which always points to the active version. 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 IS0-3166 Country Codes)"
Resources
POST /hunt v0.2 (default)
Specific versioned endpoint: /v0.2/hunt
Description: Creates a paginated Orca AI Hunt report. Returns up to 100 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.1/hunt v0.1
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
}
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"
},
"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",
"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://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. 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/huntThe unversioned form is:
https://api.orcaai.io/huntUsage 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"]
}
}
]
}v0.1 Examples (Legacy)
Example 1: Basic Person Search
curl --location --request POST "https://api.orcaai.io/v0.1/hunt" \
--header "x-api-key: your-api-key-here" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "Vladimir Putin"
}'Example 2: Company Search
curl --location --request POST "https://api.orcaai.io/v0.1/hunt" \
--header "x-api-key: your-api-key-here" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "Gazprom"
}'Example Response
{
"query": "Vladimir Putin",
"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
- 200 OK: Success! Your query has been processed.
- 400 Bad Request: The request was invalid. Check your JSON format and required fields.
- 401 Unauthorized: Invalid or missing API key.
- 403 Forbidden: Request refused due to rate limiting or insufficient permissions.
- 404 Not Found: The requested endpoint does not exist.
- 429 Too Many Requests: Rate limit exceeded. Please wait before making more requests.
- 500 Internal Server Error: An unexpected error occurred on our servers.
- 502 Bad Gateway: Orca AI is temporarily unavailable or being upgraded.
- 503 Service Unavailable: Our servers are temporarily overloaded. Please try again later.
Error Response Format
{
"error": {
"code": 400,
"message": "Invalid request format",
"details": "The 'query' field is required and cannot be empty"
}
}