The Companies API from OKKI Go (go.okki.ai) — 4 operations for B2B company search, unlock, profile and decision-maker email retrieval.
openapi: 3.0.3
info:
title: OKKI Go Companies API
description: OKKI Go is a B2B prospecting engine for AI agents and sales teams from Xiaoman (小满科技, an Alibaba company). Search global B2B companies, unlock company profiles and decision-maker contact emails, send batch or personalized cold outreach email (EDM), and track delivery — designed to be driven from AI agents via the provider-published OKKI Go Agent Skill. This OpenAPI was generated by API Evangelist from the provider's published API reference shipped inside the @okki-global/okki-go npm package (skill/references/api-reference.md, v1.3.4); endpoint paths, parameters, billing notes, and error semantics are taken verbatim from that document. Errors use RFC 7807 Problem Details. All authenticated endpoints share a 60 requests/minute rate limit.
version: 1.0.0
x-generated: '2026-07-21'
x-method: generated
x-source: npm @okki-global/okki-go 1.3.4 skill/references/api-reference.md
servers:
- url: https://go.okki.ai
description: OKKI Go production
tags:
- name: Companies
paths:
/api/v1/companies/search-advanced:
post:
operationId: searchCompaniesAdvanced
tags:
- Companies
summary: Search companies (advanced profile search)
description: Free (no points deducted). Multi-dimensional company-profile search. At least one of companyTypeKeywords, productKeywords, or industryKeywords must be non-empty; country fields are filters only. Only the listed fields are supported — filters such as employee_range, decision_roles, website, or limit do not exist.
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
companyTypeKeywords:
type: array
items:
type: string
description: Company-type keywords
productKeywords:
type: array
items:
type: string
description: Product keywords
industryKeywords:
type: array
items:
type: string
description: Industry keywords
includeCountry:
type: array
items:
type: string
description: ISO 3166-1 alpha-2 country codes to include
excludeCountry:
type: array
items:
type: string
description: ISO 3166-1 alpha-2 country codes to exclude
withEmails:
type: integer
enum:
- 0
- 1
description: Only return companies with emails
crossFieldOperator:
type: string
enum:
- AND
- OR
description: Cross-field match logic
from:
type: integer
default: 0
description: Pagination offset
size:
type: integer
default: 10
maximum: 50
description: Page size (max 50)
responses:
'200':
description: Company list
content:
application/json:
schema:
type: object
properties:
total:
type: integer
list:
type: array
items:
type: object
properties:
id:
type: string
description: Free-search id (NOT a companyHashId)
company_name:
type: string
domain:
type: string
description: Internal key used for unlock
country_code:
type: string
company_type:
type: array
items:
type: string
industry:
type: array
items:
type: string
main_products:
type: array
items:
type: string
company_profile:
type: string
founding_time:
type: string
employees_count:
type: string
email_count:
type: integer
whatsapp_count:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/companies/unlock:
post:
operationId: unlockCompany
tags:
- Companies
summary: Unlock a company (resolve domain to companyHashId)
description: First unlock of a domain costs 1 search point; re-unlocking the same domain within 30 days is free. The returned companyHashId is the only valid key for profile and profileEmails lookups. 404 (no match) is not charged.
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- countryCode
properties:
domain:
type: string
description: Company domain from search-advanced results
countryCode:
type: string
description: ISO 3166-1 alpha-2
responses:
'200':
description: Unlocked
content:
application/json:
schema:
type: object
properties:
companyHashId:
type: string
companyName:
type: string
charged:
type: boolean
alreadyViewed:
type: boolean
'402':
$ref: '#/components/responses/InsufficientCredits'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/companies/{companyHashId}/profile:
get:
operationId: getCompanyProfile
tags:
- Companies
summary: Get an unlocked company profile
description: Free (pure query). Requires a companyHashId obtained from /companies/unlock. Includes firmographics and trade data.
security:
- apiKey: []
parameters:
- name: companyHashId
in: path
required: true
schema:
type: string
description: Company hash id from /companies/unlock
responses:
'200':
description: Company profile
content:
application/json:
schema:
type: object
properties:
companyHashId:
type: string
name:
type: string
country:
type: string
industry:
type: string
employeeCount:
type: integer
website:
type: string
description:
type: string
tradeData:
type: array
items:
type: object
properties:
hsCode:
type: string
value:
type: number
date:
type: string
direction:
type: string
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/companies/{companyHashId}/profileEmails:
get:
operationId: getCompanyProfileEmails
tags:
- Companies
summary: Get contact emails for an unlocked company
description: Free (pure query). Requires companyHashId from /companies/unlock. May be called in parallel across companies.
security:
- apiKey: []
parameters:
- name: companyHashId
in: path
required: true
schema:
type: string
- name: keyword
in: query
required: false
schema:
type: string
description: Filter contacts by title/name keyword
- name: page
in: query
required: false
schema:
type: integer
- name: pageSize
in: query
required: false
schema:
type: integer
maximum: 100
responses:
'200':
description: Contact emails (empty array when none available)
content:
application/json:
schema:
type: object
properties:
emails:
type: array
items:
type: object
properties:
name:
type: string
title:
type: string
email:
type: string
linkedin:
type: string
total:
type: integer
page:
type: integer
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Problem:
type: object
description: RFC 7807 Problem Details error envelope.
properties:
type:
type: string
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
code:
type: string
responses:
InsufficientCredits:
description: 'RFC 7807 insufficient-credits: search points or EDM quota exhausted'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
Unauthorized:
description: 'RFC 7807 unauthorized: API key missing, invalid, or revoked'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
BadRequest:
description: 'RFC 7807 bad-request: malformed parameters'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
NotFound:
description: 'RFC 7807 not-found: resource does not exist or belongs to another user'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
RateLimited:
description: 'RFC 7807 rate-limit / quota-exceeded: 60 requests/minute shared across authenticated endpoints'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: 'Authorization: ApiKey sk-your-key-here — API keys issued at https://go.okki.ai after registration.'