KosmoKrator

data

Clearbit Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Clearbit KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.clearbit.*. Use lua_read_doc("integrations.clearbit") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Clearbit workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.clearbit.api_get({api = "example_api", path = "example_path", params = "example_params"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("clearbit"))' --json
kosmo integrations:lua --eval 'print(docs.read("clearbit.api_get"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local clearbit = app.integrations.clearbit
local result = clearbit.api_get({api = "example_api", path = "example_path", params = "example_params"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.clearbit, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.clearbit.default.* or app.integrations.clearbit.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Clearbit, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Clearbit Lua API Reference

Namespace: app.integrations.clearbit

Clearbit exposes B2B person, company, reveal, prospector, discovery, autocomplete, name-to-domain, and risk APIs. Most tools require an API key. list_autocomplete is public. Name-to-domain and risk are legacy unsupported APIs for existing Clearbit customers.

Enrichment

local person = app.integrations.clearbit.enrich_person({
  email = "person@example.test"
})

local combined = app.integrations.clearbit.enrich_combined({
  email = "person@example.test"
})

local company = app.integrations.clearbit.enrich_company({
  domain = "example.test"
})

enrich_combined returns Clearbit’s combined person/company response. Use it when you need both the individual contact and company context from one email lookup.

Reveal

local reveal = app.integrations.clearbit.reveal({
  ip = "203.0.113.10"
})

Reveal identifies the company associated with an IP address. It does not identify the specific person visiting the site.

Prospector

local prospects = app.integrations.clearbit.prospect({
  domain = "example.test",
  roles = "sales,engineering",
  seniority = "executive",
  page = 1
})

Useful filters include domain, role, roles, seniority, title, company, and page.

Company Lookup

local suggestions = app.integrations.clearbit.list_autocomplete({
  name = "Example"
})

local domain = app.integrations.clearbit.name_to_domain({
  name = "Example"
})

Autocomplete is public and returns matching company names, domains, and logos. Name-to-domain requires an existing Clearbit API key and may be unavailable for new accounts.

Discovery And Risk

local companies = app.integrations.clearbit.discovery_search({
  params = {
    query = "name:example",
    limit = 10
  }
})

local risk = app.integrations.clearbit.calculate_risk({
  params = {
    email = "person@example.test",
    ip = "203.0.113.10",
    name = "Example Person"
  }
})

Risk is a legacy unsupported API. Treat errors from this endpoint as a plan or product-availability issue unless credentials are known to have Risk access.

Long-Tail GET Endpoints

local result = app.integrations.clearbit.api_get({
  api = "company",
  path = "/companies/find",
  params = { domain = "example.test" }
})

api must be one of person, company, autocomplete, prospector, reveal, discovery, risk, or name_to_domain. The path must be relative, not a full URL.

Multi-Account Usage

app.integrations.clearbit.enrich_company({ domain = "example.test" })
app.integrations.clearbit.default.enrich_company({ domain = "example.test" })
app.integrations.clearbit.sales.enrich_person({ email = "person@example.test" })

All functions are identical across accounts; only credentials differ.

Raw agent markdown 
# Clearbit Lua API Reference

Namespace: `app.integrations.clearbit`

Clearbit exposes B2B person, company, reveal, prospector, discovery, autocomplete, name-to-domain, and risk APIs. Most tools require an API key. `list_autocomplete` is public. Name-to-domain and risk are legacy unsupported APIs for existing Clearbit customers.

## Enrichment

```lua
local person = app.integrations.clearbit.enrich_person({
  email = "person@example.test"
})

local combined = app.integrations.clearbit.enrich_combined({
  email = "person@example.test"
})

local company = app.integrations.clearbit.enrich_company({
  domain = "example.test"
})
```

`enrich_combined` returns Clearbit's combined person/company response. Use it when you need both the individual contact and company context from one email lookup.

## Reveal

```lua
local reveal = app.integrations.clearbit.reveal({
  ip = "203.0.113.10"
})
```

Reveal identifies the company associated with an IP address. It does not identify the specific person visiting the site.

## Prospector

```lua
local prospects = app.integrations.clearbit.prospect({
  domain = "example.test",
  roles = "sales,engineering",
  seniority = "executive",
  page = 1
})
```

Useful filters include `domain`, `role`, `roles`, `seniority`, `title`, `company`, and `page`.

## Company Lookup

```lua
local suggestions = app.integrations.clearbit.list_autocomplete({
  name = "Example"
})

local domain = app.integrations.clearbit.name_to_domain({
  name = "Example"
})
```

Autocomplete is public and returns matching company names, domains, and logos. Name-to-domain requires an existing Clearbit API key and may be unavailable for new accounts.

## Discovery And Risk

```lua
local companies = app.integrations.clearbit.discovery_search({
  params = {
    query = "name:example",
    limit = 10
  }
})

local risk = app.integrations.clearbit.calculate_risk({
  params = {
    email = "person@example.test",
    ip = "203.0.113.10",
    name = "Example Person"
  }
})
```

Risk is a legacy unsupported API. Treat errors from this endpoint as a plan or product-availability issue unless credentials are known to have Risk access.

## Long-Tail GET Endpoints

```lua
local result = app.integrations.clearbit.api_get({
  api = "company",
  path = "/companies/find",
  params = { domain = "example.test" }
})
```

`api` must be one of `person`, `company`, `autocomplete`, `prospector`, `reveal`, `discovery`, `risk`, or `name_to_domain`. The path must be relative, not a full URL.

## Multi-Account Usage

```lua
app.integrations.clearbit.enrich_company({ domain = "example.test" })
app.integrations.clearbit.default.enrich_company({ domain = "example.test" })
app.integrations.clearbit.sales.enrich_person({ email = "person@example.test" })
```

All functions are identical across accounts; only credentials differ.
Metadata-derived Lua example 
local result = app.integrations.clearbit.api_get({api = "example_api", path = "example_path", params = "example_params"})
print(result)

Functions

api_get Read

Call a read-only Clearbit GET endpoint on a named API host such as person, company, reveal, prospector, discovery, risk, name_to_domain, or autocomplete.

Lua path
app.integrations.clearbit.api_get
Full name
clearbit.clearbit_api_get
ParameterTypeRequiredDescription
api string yes API host key: person, company, reveal, prospector, discovery, risk, name_to_domain, or autocomplete.
path string yes Relative endpoint path such as /companies/find.
params object no Query parameters.
calculate_risk Read

Calculate a Clearbit Risk score from email, IP, and optional identity fields. This is a legacy unsupported API for existing Clearbit customers.

Lua path
app.integrations.clearbit.calculate_risk
Full name
clearbit.clearbit_calculate_risk
ParameterTypeRequiredDescription
params object yes Risk inputs such as email, ip, name, country_code, zip_code, given_name, family_name.
enrich_combined Read

Look up a person and associated company by email using Clearbit combined enrichment.

Lua path
app.integrations.clearbit.enrich_combined
Full name
clearbit.clearbit_enrich_combined
ParameterTypeRequiredDescription
email string yes Email address to enrich.
enrich_company Read

Look up a company by domain name using Clearbit. Returns company metrics, industry categorization, social profiles, and funding data when available.

Lua path
app.integrations.clearbit.enrich_company
Full name
clearbit.clearbit_enrich_company
ParameterTypeRequiredDescription
domain string yes The company domain to look up (e.g., "example.test").
enrich_person Read

Look up a person by email address using Clearbit. Returns social profiles, employment, location, and demographic data when available.

Lua path
app.integrations.clearbit.enrich_person
Full name
clearbit.clearbit_enrich_person
ParameterTypeRequiredDescription
email string yes The email address of the person to look up (e.g., "person@example.test").
list_autocomplete Read

Search for companies by name using Clearbit Autocomplete. Returns a list of matching companies with domains, logos, and descriptions. Useful for type-ahead search.

Lua path
app.integrations.clearbit.list_autocomplete
Full name
clearbit.clearbit_list_autocomplete
ParameterTypeRequiredDescription
name string yes Company name or prefix to search for (e.g., "Stripe", "Goo").
name_domain Read

Find a company domain and logo by company name using Clearbit Name to Domain. This is a legacy unsupported API for existing Clearbit customers.

Lua path
app.integrations.clearbit.name_domain
Full name
clearbit.clearbit_name_to_domain
ParameterTypeRequiredDescription
name string yes Company name, such as Segment.
prospect Read

Find people by job title and/or company name using Clearbit Prospecting. Returns names, titles, and email addresses when available.

Lua path
app.integrations.clearbit.prospect
Full name
clearbit.clearbit_prospect
ParameterTypeRequiredDescription
domain string no Company domain to search within (e.g., "example.test").
title string no Job title to search for (e.g., "CEO", "Software Engineer", "VP of Sales").
role string no Role filter such as sales or engineering.
roles string no Comma-separated role filters.
seniority string no Seniority filter such as executive, manager, or individual_contributor.
company string no Company name to filter by (e.g., "Stripe", "Google").
page integer no Page number for pagination (default: 1).
reveal Read

Identify the company behind an IP address using Clearbit Reveal.

Lua path
app.integrations.clearbit.reveal
Full name
clearbit.clearbit_reveal
ParameterTypeRequiredDescription
ip string yes The IP address to look up (IPv4 or IPv6, e.g., "203.0.113.10").