KosmoKrator

productivity

Affinity Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.affinity.*. Use lua_read_doc("integrations.affinity") 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 Affinity workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.affinity.get_current_user({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("affinity"))' --json
kosmo integrations:lua --eval 'print(docs.read("affinity.get_current_user"))' --json

Workflow file

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

workflow.lua 
local affinity = app.integrations.affinity
local result = affinity.get_current_user({})

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.affinity, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.affinity.default.* or app.integrations.affinity.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Affinity, 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.

Affinity Lua API Reference

Namespace: app.integrations.affinity

This integration targets Affinity API v2. List tools usually accept cursor, limit, fieldIds, fieldTypes, or a params object. Write tools accept a payload object.

Common Patterns

List persons:

local result = app.integrations.affinity.list_contacts({
  limit = 100
})

Get company field values:

local result = app.integrations.affinity.list_organization_field_values({
  company_id = "company_test",
  fieldTypes = "global,relationship-intelligence"
})

Update a list-entry field:

local result = app.integrations.affinity.update_list_entry_field({
  list_id = "list_test",
  list_entry_id = "entry_test",
  field_id = "field_test",
  value = "Qualified"
})

Semantic search:

local result = app.integrations.affinity.semantic_search({
  payload = {
    ["entity-type"] = "person",
    query = "founders in fintech"
  }
})

Coverage

Tools include persons, companies, opportunities, lists, list entries, saved views, notes, calls, emails, meetings, chat messages, transcripts, semantic search, and raw API helpers.

Raw API Helpers

local result = app.integrations.affinity.api_get({
  path = "/persons",
  params = {
    limit = 50
  }
})

The path must be relative. /persons is normalized to /v2/persons; pass an explicit /v1/... path for documented legacy endpoints.

Raw agent markdown 
# Affinity Lua API Reference

Namespace: `app.integrations.affinity`

This integration targets Affinity API v2. List tools usually accept `cursor`,
`limit`, `fieldIds`, `fieldTypes`, or a `params` object. Write tools accept a
`payload` object.

## Common Patterns

List persons:

```lua
local result = app.integrations.affinity.list_contacts({
  limit = 100
})
```

Get company field values:

```lua
local result = app.integrations.affinity.list_organization_field_values({
  company_id = "company_test",
  fieldTypes = "global,relationship-intelligence"
})
```

Update a list-entry field:

```lua
local result = app.integrations.affinity.update_list_entry_field({
  list_id = "list_test",
  list_entry_id = "entry_test",
  field_id = "field_test",
  value = "Qualified"
})
```

Semantic search:

```lua
local result = app.integrations.affinity.semantic_search({
  payload = {
    ["entity-type"] = "person",
    query = "founders in fintech"
  }
})
```

## Coverage

Tools include persons, companies, opportunities, lists, list entries, saved
views, notes, calls, emails, meetings, chat messages, transcripts, semantic
search, and raw API helpers.

## Raw API Helpers

```lua
local result = app.integrations.affinity.api_get({
  path = "/persons",
  params = {
    limit = 50
  }
})
```

The `path` must be relative. `/persons` is normalized to `/v2/persons`; pass an
explicit `/v1/...` path for documented legacy endpoints.
Metadata-derived Lua example 
local result = app.integrations.affinity.get_current_user({})
print(result)

Functions

get_current_user Read

Get the authenticated Affinity user and API permissions.

Lua path
app.integrations.affinity.get_current_user
Full name
affinity.affinity_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_persons Read

List persons in Affinity.

Lua path
app.integrations.affinity.list_persons
Full name
affinity.affinity_list_contacts
ParameterTypeRequiredDescription
No parameters.
get_person Read

Get a person by ID.

Lua path
app.integrations.affinity.get_person
Full name
affinity.affinity_get_contact
ParameterTypeRequiredDescription
No parameters.
create_person Write

Create a person using Affinity API.

Lua path
app.integrations.affinity.create_person
Full name
affinity.affinity_create_contact
ParameterTypeRequiredDescription
No parameters.
list_person_fields Read

List person field metadata.

Lua path
app.integrations.affinity.list_person_fields
Full name
affinity.affinity_list_contact_fields
ParameterTypeRequiredDescription
No parameters.
list_person_field_values Read

List field values on a person.

Lua path
app.integrations.affinity.list_person_field_values
Full name
affinity.affinity_list_contact_field_values
ParameterTypeRequiredDescription
No parameters.
get_person_field_value Read

Get a single field value on a person.

Lua path
app.integrations.affinity.get_person_field_value
Full name
affinity.affinity_get_contact_field_value
ParameterTypeRequiredDescription
No parameters.
list_person_lists Read

List lists where a person appears.

Lua path
app.integrations.affinity.list_person_lists
Full name
affinity.affinity_list_contact_lists
ParameterTypeRequiredDescription
No parameters.
list_person_list_entries Read

List list entries for a person.

Lua path
app.integrations.affinity.list_person_list_entries
Full name
affinity.affinity_list_contact_list_entries
ParameterTypeRequiredDescription
No parameters.
list_person_notes Read

List notes related to a person.

Lua path
app.integrations.affinity.list_person_notes
Full name
affinity.affinity_list_contact_notes
ParameterTypeRequiredDescription
No parameters.
list_companies Read

List companies in Affinity.

Lua path
app.integrations.affinity.list_companies
Full name
affinity.affinity_list_organizations
ParameterTypeRequiredDescription
No parameters.
get_company Read

Get a company by ID.

Lua path
app.integrations.affinity.get_company
Full name
affinity.affinity_get_organization
ParameterTypeRequiredDescription
No parameters.
create_company Write

Create a company using Affinity API.

Lua path
app.integrations.affinity.create_company
Full name
affinity.affinity_create_organization
ParameterTypeRequiredDescription
No parameters.
list_company_fields Read

List company field metadata.

Lua path
app.integrations.affinity.list_company_fields
Full name
affinity.affinity_list_organization_fields
ParameterTypeRequiredDescription
No parameters.
list_company_field_values Read

List field values on a company.

Lua path
app.integrations.affinity.list_company_field_values
Full name
affinity.affinity_list_organization_field_values
ParameterTypeRequiredDescription
No parameters.
get_company_field_value Read

Get a single field value on a company.

Lua path
app.integrations.affinity.get_company_field_value
Full name
affinity.affinity_get_organization_field_value
ParameterTypeRequiredDescription
No parameters.
list_company_lists Read

List lists where a company appears.

Lua path
app.integrations.affinity.list_company_lists
Full name
affinity.affinity_list_organization_lists
ParameterTypeRequiredDescription
No parameters.
list_company_list_entries Read

List list entries for a company.

Lua path
app.integrations.affinity.list_company_list_entries
Full name
affinity.affinity_list_organization_list_entries
ParameterTypeRequiredDescription
No parameters.
list_company_notes Read

List notes related to a company.

Lua path
app.integrations.affinity.list_company_notes
Full name
affinity.affinity_list_organization_notes
ParameterTypeRequiredDescription
No parameters.
list_opportunities Read

List opportunities in Affinity.

Lua path
app.integrations.affinity.list_opportunities
Full name
affinity.affinity_list_opportunities
ParameterTypeRequiredDescription
No parameters.
get_opportunity Read

Get an opportunity by ID.

Lua path
app.integrations.affinity.get_opportunity
Full name
affinity.affinity_get_opportunity
ParameterTypeRequiredDescription
No parameters.
list_opportunity_notes Read

List notes related to an opportunity.

Lua path
app.integrations.affinity.list_opportunity_notes
Full name
affinity.affinity_list_opportunity_notes
ParameterTypeRequiredDescription
No parameters.
list_lists Read

List Affinity lists.

Lua path
app.integrations.affinity.list_lists
Full name
affinity.affinity_list_lists
ParameterTypeRequiredDescription
No parameters.
get_list Read

Get metadata for a list.

Lua path
app.integrations.affinity.get_list
Full name
affinity.affinity_get_list
ParameterTypeRequiredDescription
No parameters.
list_list_fields Read

List field metadata for a list.

Lua path
app.integrations.affinity.list_list_fields
Full name
affinity.affinity_list_list_fields
ParameterTypeRequiredDescription
No parameters.
list_list_entries Read

List entries on a list.

Lua path
app.integrations.affinity.list_list_entries
Full name
affinity.affinity_list_list_entries
ParameterTypeRequiredDescription
No parameters.
get_list_entry Read

Get one list entry.

Lua path
app.integrations.affinity.get_list_entry
Full name
affinity.affinity_get_list_entry
ParameterTypeRequiredDescription
No parameters.
list_list_entry_fields Read

List field values on a list entry.

Lua path
app.integrations.affinity.list_list_entry_fields
Full name
affinity.affinity_list_list_entry_fields
ParameterTypeRequiredDescription
No parameters.
get_list_entry_field Read

Get one field value on a list entry.

Lua path
app.integrations.affinity.get_list_entry_field
Full name
affinity.affinity_get_list_entry_field
ParameterTypeRequiredDescription
No parameters.
update_list_entry_field Write

Update one field value on a list entry.

Lua path
app.integrations.affinity.update_list_entry_field
Full name
affinity.affinity_update_list_entry_field
ParameterTypeRequiredDescription
No parameters.
batch_update_list_entry_fields Write

Batch update field values on a list entry.

Lua path
app.integrations.affinity.batch_update_list_entry_fields
Full name
affinity.affinity_batch_update_list_entry_fields
ParameterTypeRequiredDescription
No parameters.
list_saved_views Read

List saved views for a list.

Lua path
app.integrations.affinity.list_saved_views
Full name
affinity.affinity_list_saved_views
ParameterTypeRequiredDescription
No parameters.
get_saved_view Read

Get saved view metadata.

Lua path
app.integrations.affinity.get_saved_view
Full name
affinity.affinity_get_saved_view
ParameterTypeRequiredDescription
No parameters.
list_saved_view_entries Read

List entries on a saved view.

Lua path
app.integrations.affinity.list_saved_view_entries
Full name
affinity.affinity_list_saved_view_entries
ParameterTypeRequiredDescription
No parameters.
list_notes Read

List notes.

Lua path
app.integrations.affinity.list_notes
Full name
affinity.affinity_list_notes
ParameterTypeRequiredDescription
No parameters.
get_note Read

Get a note by ID.

Lua path
app.integrations.affinity.get_note
Full name
affinity.affinity_get_note
ParameterTypeRequiredDescription
No parameters.
list_note_replies Read

List replies for a note.

Lua path
app.integrations.affinity.list_note_replies
Full name
affinity.affinity_list_note_replies
ParameterTypeRequiredDescription
No parameters.
list_note_persons Read

List persons attached to a note.

Lua path
app.integrations.affinity.list_note_persons
Full name
affinity.affinity_list_note_persons
ParameterTypeRequiredDescription
No parameters.
list_note_companies Read

List companies attached to a note.

Lua path
app.integrations.affinity.list_note_companies
Full name
affinity.affinity_list_note_companies
ParameterTypeRequiredDescription
No parameters.
list_note_opportunities Read

List opportunities attached to a note.

Lua path
app.integrations.affinity.list_note_opportunities
Full name
affinity.affinity_list_note_opportunities
ParameterTypeRequiredDescription
No parameters.
list_calls Read

List call interactions.

Lua path
app.integrations.affinity.list_calls
Full name
affinity.affinity_list_calls
ParameterTypeRequiredDescription
No parameters.
list_emails Read

List email interactions.

Lua path
app.integrations.affinity.list_emails
Full name
affinity.affinity_list_emails
ParameterTypeRequiredDescription
No parameters.
list_meetings Read

List meeting interactions.

Lua path
app.integrations.affinity.list_meetings
Full name
affinity.affinity_list_meetings
ParameterTypeRequiredDescription
No parameters.
list_chat_messages Read

List chat message interactions.

Lua path
app.integrations.affinity.list_chat_messages
Full name
affinity.affinity_list_chat_messages
ParameterTypeRequiredDescription
No parameters.
list_transcripts Read

List transcripts.

Lua path
app.integrations.affinity.list_transcripts
Full name
affinity.affinity_list_transcripts
ParameterTypeRequiredDescription
No parameters.
get_transcript Read

Get a transcript by ID.

Lua path
app.integrations.affinity.get_transcript
Full name
affinity.affinity_get_transcript
ParameterTypeRequiredDescription
No parameters.
list_transcript_fragments Read

List fragments for a transcript.

Lua path
app.integrations.affinity.list_transcript_fragments
Full name
affinity.affinity_list_transcript_fragments
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Affinity API path with GET.

Lua path
app.integrations.affinity.api_get
Full name
affinity.affinity_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative Affinity API path with POST.

Lua path
app.integrations.affinity.api_post
Full name
affinity.affinity_api_post
ParameterTypeRequiredDescription
No parameters.
api_put Write

Call a safe relative Affinity API path with PUT.

Lua path
app.integrations.affinity.api_put
Full name
affinity.affinity_api_put
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative Affinity API path with DELETE.

Lua path
app.integrations.affinity.api_delete
Full name
affinity.affinity_api_delete
ParameterTypeRequiredDescription
No parameters.