KosmoKrator

productivity

Front Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.front.api_get({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("front"))' --json
kosmo integrations:lua --eval 'print(docs.read("front.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 front = app.integrations.front
local result = front.api_get({})

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

MCP-only Lua

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

Front Lua API Reference

Namespace: app.integrations.front

Front tools call the Front Core API with the configured bearer token. Most list endpoints return Front’s normal paginated shape, usually _results plus _pagination; use page_token from _pagination.next when Front returns one. JSON helpers do not upload files. Use raw API helpers or a host-specific upload flow for multipart attachment and avatar endpoints.

Raw API helpers

Use these when Front adds a new endpoint before a typed helper exists:

  • api_get({ path = "/tags", query = { limit = 25 } })
  • api_post({ path = "/contacts", body = { handles = {{ source = "email", handle = "person@example.test" }} } })
  • api_patch({ path = "/contacts/crd_123", body = { custom_fields = { Tier = "Gold" } } })
  • api_put({ path = "/some/path", body = {} })
  • api_delete({ path = "/tags/tag_123" })

Paths are relative to https://api2.frontapp.com; a leading slash is optional.

Conversations, Messages, and Comments

  • get_current_user({})
  • list_conversations({ q, limit, page_token, page, status })
  • search_conversations({ query_text, limit, page_token })
  • get_conversation({ conversation_id })
  • create_discussion_conversation({ type = "discussion", inbox_id, teammate_ids, subject, comment, custom_fields })
  • update_conversation({ conversation_id, assignee_id, inbox_id, status, status_id, tag_ids, custom_fields })
  • update_conversation_reminders({ conversation_id, teammate_id, scheduled_at, status_id })
  • list_conversation_inboxes({ conversation_id })
  • list_messages({ conversation_id, limit, page_token, sort_by, sort_order })
  • get_message({ message_id })
  • send_message({ conversation_id, channel_id, author_id, to, cc, bcc, subject, body, text, quote_body, options })
  • create_message({ channel_id, to, cc, bcc, subject, body, text, author_id })
  • import_message({ inbox_id, sender, to, external_id, created_at, body, metadata, tags })
  • create_draft({ channel_id, to, cc, bcc, subject, body, author_id })
  • list_conversation_comments({ conversation_id })
  • add_comment({ conversation_id, body, author_id, is_pinned })
  • add_conversation_tags({ conversation_id, tag_ids })
  • remove_conversation_tags({ conversation_id, tag_ids })

Example:

local conversations = app.integrations.front.search_conversations({
  query_text = "billing is:open",
  limit = 10
})

local first = conversations._results and conversations._results[1]
if first then
  app.integrations.front.add_comment({
    conversation_id = first.id,
    body = "Followed up from automation."
  })
end

Inboxes and Channels

  • list_inboxes({ limit, page_token })
  • get_inbox({ inbox_id })
  • list_inbox_conversations({ inbox_id, q, limit, page_token })
  • list_inbox_channels({ inbox_id })
  • create_channel({ inbox_id, type, name, send_as, settings })
  • list_inbox_access({ inbox_id })
  • add_inbox_access({ inbox_id, teammate_ids })
  • remove_inbox_access({ inbox_id, teammate_ids })
  • create_team_inbox({ team_id, name, teammate_ids, is_public, custom_fields })

Contacts

  • list_contacts({ q, limit, page_token, sort_by, sort_order })
  • get_contact({ contact_id })
  • create_contact({ handles, name, description, links, list_names, custom_fields })
  • create_teammate_contact({ teammate_id, handles, name, description, links, list_names, custom_fields })
  • update_contact({ contact_id, name, description, links, list_names, custom_fields })
  • delete_contact({ contact_id })
  • add_contact_handle({ contact_id, handle, source })
  • list_contact_conversations({ contact_id, q, limit, page_token })
  • list_team_contacts({ team_id, q, limit, page_token, sort_by, sort_order })
  • list_teammate_contacts({ teammate_id, q, limit, page_token, sort_by, sort_order })

Contact aliases are supported where Front supports them, for example alt:email:person@example.test.

Teams, Teammates, Rules, and Tags

  • list_teammates({})
  • get_teammate({ teammate_id })
  • update_teammate({ teammate_id, body })
  • list_assigned_conversations({ teammate_id, q, limit, page_token })
  • list_teammate_inboxes({ teammate_id })
  • list_teammate_rules({ teammate_id })
  • list_teams({})
  • get_team({ team_id })
  • list_team_inboxes({ team_id })
  • list_team_rules({ team_id })
  • list_tags({ limit, page_token, sort_by, sort_order })
  • get_tag({ tag_id })
  • create_tag({ name, description, highlight, is_visible_in_conversation_lists })
  • create_company_tag({ name, description, highlight, is_visible_in_conversation_lists })
  • create_team_tag({ team_id, name, description, highlight, is_visible_in_conversation_lists })
  • create_teammate_tag({ teammate_id, name, description, highlight, is_visible_in_conversation_lists })
  • update_tag({ tag_id, name, description, highlight, parent_tag_id, is_visible_in_conversation_lists })
  • delete_tag({ tag_id })
  • list_tagged_conversations({ tag_id, q, limit, page_token })
  • list_company_tags({ limit, page_token, sort_by, sort_order })
  • list_team_tags({ team_id, limit, page_token, sort_by, sort_order })
  • list_teammate_tags({ teammate_id, limit, page_token, sort_by, sort_order })

Multi-Account Usage

app.integrations.front.list_conversations({ limit = 10 })
app.integrations.front.default.list_conversations({ limit = 10 })
app.integrations.front.support.list_conversations({ limit = 10 })

The tool names and return shapes are the same for each account; only credentials differ.

Raw agent markdown 
# Front Lua API Reference

Namespace: `app.integrations.front`

Front tools call the Front Core API with the configured bearer token. Most list endpoints return Front's normal paginated shape, usually `_results` plus `_pagination`; use `page_token` from `_pagination.next` when Front returns one. JSON helpers do not upload files. Use raw API helpers or a host-specific upload flow for multipart attachment and avatar endpoints.

## Raw API helpers

Use these when Front adds a new endpoint before a typed helper exists:

- `api_get({ path = "/tags", query = { limit = 25 } })`
- `api_post({ path = "/contacts", body = { handles = {{ source = "email", handle = "person@example.test" }} } })`
- `api_patch({ path = "/contacts/crd_123", body = { custom_fields = { Tier = "Gold" } } })`
- `api_put({ path = "/some/path", body = {} })`
- `api_delete({ path = "/tags/tag_123" })`

Paths are relative to `https://api2.frontapp.com`; a leading slash is optional.

## Conversations, Messages, and Comments

- `get_current_user({})`
- `list_conversations({ q, limit, page_token, page, status })`
- `search_conversations({ query_text, limit, page_token })`
- `get_conversation({ conversation_id })`
- `create_discussion_conversation({ type = "discussion", inbox_id, teammate_ids, subject, comment, custom_fields })`
- `update_conversation({ conversation_id, assignee_id, inbox_id, status, status_id, tag_ids, custom_fields })`
- `update_conversation_reminders({ conversation_id, teammate_id, scheduled_at, status_id })`
- `list_conversation_inboxes({ conversation_id })`
- `list_messages({ conversation_id, limit, page_token, sort_by, sort_order })`
- `get_message({ message_id })`
- `send_message({ conversation_id, channel_id, author_id, to, cc, bcc, subject, body, text, quote_body, options })`
- `create_message({ channel_id, to, cc, bcc, subject, body, text, author_id })`
- `import_message({ inbox_id, sender, to, external_id, created_at, body, metadata, tags })`
- `create_draft({ channel_id, to, cc, bcc, subject, body, author_id })`
- `list_conversation_comments({ conversation_id })`
- `add_comment({ conversation_id, body, author_id, is_pinned })`
- `add_conversation_tags({ conversation_id, tag_ids })`
- `remove_conversation_tags({ conversation_id, tag_ids })`

Example:

```lua
local conversations = app.integrations.front.search_conversations({
  query_text = "billing is:open",
  limit = 10
})

local first = conversations._results and conversations._results[1]
if first then
  app.integrations.front.add_comment({
    conversation_id = first.id,
    body = "Followed up from automation."
  })
end
```

## Inboxes and Channels

- `list_inboxes({ limit, page_token })`
- `get_inbox({ inbox_id })`
- `list_inbox_conversations({ inbox_id, q, limit, page_token })`
- `list_inbox_channels({ inbox_id })`
- `create_channel({ inbox_id, type, name, send_as, settings })`
- `list_inbox_access({ inbox_id })`
- `add_inbox_access({ inbox_id, teammate_ids })`
- `remove_inbox_access({ inbox_id, teammate_ids })`
- `create_team_inbox({ team_id, name, teammate_ids, is_public, custom_fields })`

## Contacts

- `list_contacts({ q, limit, page_token, sort_by, sort_order })`
- `get_contact({ contact_id })`
- `create_contact({ handles, name, description, links, list_names, custom_fields })`
- `create_teammate_contact({ teammate_id, handles, name, description, links, list_names, custom_fields })`
- `update_contact({ contact_id, name, description, links, list_names, custom_fields })`
- `delete_contact({ contact_id })`
- `add_contact_handle({ contact_id, handle, source })`
- `list_contact_conversations({ contact_id, q, limit, page_token })`
- `list_team_contacts({ team_id, q, limit, page_token, sort_by, sort_order })`
- `list_teammate_contacts({ teammate_id, q, limit, page_token, sort_by, sort_order })`

Contact aliases are supported where Front supports them, for example `alt:email:person@example.test`.

## Teams, Teammates, Rules, and Tags

- `list_teammates({})`
- `get_teammate({ teammate_id })`
- `update_teammate({ teammate_id, body })`
- `list_assigned_conversations({ teammate_id, q, limit, page_token })`
- `list_teammate_inboxes({ teammate_id })`
- `list_teammate_rules({ teammate_id })`
- `list_teams({})`
- `get_team({ team_id })`
- `list_team_inboxes({ team_id })`
- `list_team_rules({ team_id })`
- `list_tags({ limit, page_token, sort_by, sort_order })`
- `get_tag({ tag_id })`
- `create_tag({ name, description, highlight, is_visible_in_conversation_lists })`
- `create_company_tag({ name, description, highlight, is_visible_in_conversation_lists })`
- `create_team_tag({ team_id, name, description, highlight, is_visible_in_conversation_lists })`
- `create_teammate_tag({ teammate_id, name, description, highlight, is_visible_in_conversation_lists })`
- `update_tag({ tag_id, name, description, highlight, parent_tag_id, is_visible_in_conversation_lists })`
- `delete_tag({ tag_id })`
- `list_tagged_conversations({ tag_id, q, limit, page_token })`
- `list_company_tags({ limit, page_token, sort_by, sort_order })`
- `list_team_tags({ team_id, limit, page_token, sort_by, sort_order })`
- `list_teammate_tags({ teammate_id, limit, page_token, sort_by, sort_order })`

## Multi-Account Usage

```lua
app.integrations.front.list_conversations({ limit = 10 })
app.integrations.front.default.list_conversations({ limit = 10 })
app.integrations.front.support.list_conversations({ limit = 10 })
```

The tool names and return shapes are the same for each account; only credentials differ.
Metadata-derived Lua example 
local result = app.integrations.front.api_get({})
print(result)

Functions

api_get Read

Call any Front GET endpoint.

Lua path
app.integrations.front.api_get
Full name
front.front_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call any Front POST endpoint.

Lua path
app.integrations.front.api_post
Full name
front.front_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call any Front PATCH endpoint.

Lua path
app.integrations.front.api_patch
Full name
front.front_api_patch
ParameterTypeRequiredDescription
No parameters.
api_put Write

Call any Front PUT endpoint.

Lua path
app.integrations.front.api_put
Full name
front.front_api_put
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call any Front DELETE endpoint.

Lua path
app.integrations.front.api_delete
Full name
front.front_api_delete
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the authenticated Front user.

Lua path
app.integrations.front.get_current_user
Full name
front.front_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_conversations Read

List Front conversations.

Lua path
app.integrations.front.list_conversations
Full name
front.front_list_conversations
ParameterTypeRequiredDescription
No parameters.
search_conversations Read

Search Front conversations using search syntax.

Lua path
app.integrations.front.search_conversations
Full name
front.front_search_conversations
ParameterTypeRequiredDescription
No parameters.
get_conversation Read

Get a Front conversation.

Lua path
app.integrations.front.get_conversation
Full name
front.front_get_conversation
ParameterTypeRequiredDescription
No parameters.
create_discussion_conversation Write

Create a comment-only discussion conversation.

Lua path
app.integrations.front.create_discussion_conversation
Full name
front.front_create_discussion_conversation
ParameterTypeRequiredDescription
No parameters.
update_conversation Write

Update a Front conversation.

Lua path
app.integrations.front.update_conversation
Full name
front.front_update_conversation
ParameterTypeRequiredDescription
No parameters.
update_conversation_reminders Write

Snooze or unsnooze a Front conversation.

Lua path
app.integrations.front.update_conversation_reminders
Full name
front.front_update_conversation_reminders
ParameterTypeRequiredDescription
No parameters.
list_conversation_inboxes Read

List inboxes for a conversation.

Lua path
app.integrations.front.list_conversation_inboxes
Full name
front.front_list_conversation_inboxes
ParameterTypeRequiredDescription
No parameters.
list_messages Read

List messages in a conversation.

Lua path
app.integrations.front.list_messages
Full name
front.front_list_messages
ParameterTypeRequiredDescription
No parameters.
get_message Read

Get a Front message.

Lua path
app.integrations.front.get_message
Full name
front.front_get_message
ParameterTypeRequiredDescription
No parameters.
send_message_reply Write

Reply to a Front conversation.

Lua path
app.integrations.front.send_message_reply
Full name
front.front_send_message
ParameterTypeRequiredDescription
No parameters.
create_message Write

Send a new message from a Front channel.

Lua path
app.integrations.front.create_message
Full name
front.front_create_message
ParameterTypeRequiredDescription
No parameters.
import_message Write

Import an external message into a Front inbox.

Lua path
app.integrations.front.import_message
Full name
front.front_import_message
ParameterTypeRequiredDescription
No parameters.
create_draft Write

Create a draft in a Front channel.

Lua path
app.integrations.front.create_draft
Full name
front.front_create_draft
ParameterTypeRequiredDescription
No parameters.
list_conversation_comments Read

List comments in a conversation.

Lua path
app.integrations.front.list_conversation_comments
Full name
front.front_list_conversation_comments
ParameterTypeRequiredDescription
No parameters.
add_comment Write

Add a comment to a conversation.

Lua path
app.integrations.front.add_comment
Full name
front.front_add_comment
ParameterTypeRequiredDescription
No parameters.
add_conversation_tags Write

Add tags to a conversation.

Lua path
app.integrations.front.add_conversation_tags
Full name
front.front_add_conversation_tags
ParameterTypeRequiredDescription
No parameters.
remove_conversation_tags Write

Remove tags from a conversation.

Lua path
app.integrations.front.remove_conversation_tags
Full name
front.front_remove_conversation_tags
ParameterTypeRequiredDescription
No parameters.
list_inboxes Read

List Front inboxes.

Lua path
app.integrations.front.list_inboxes
Full name
front.front_list_inboxes
ParameterTypeRequiredDescription
No parameters.
get_inbox Read

Get a Front inbox.

Lua path
app.integrations.front.get_inbox
Full name
front.front_get_inbox
ParameterTypeRequiredDescription
No parameters.
list_inbox_conversations Read

List conversations in an inbox.

Lua path
app.integrations.front.list_inbox_conversations
Full name
front.front_list_inbox_conversations
ParameterTypeRequiredDescription
No parameters.
list_inbox_channels Read

List channels in an inbox.

Lua path
app.integrations.front.list_inbox_channels
Full name
front.front_list_inbox_channels
ParameterTypeRequiredDescription
No parameters.
create_channel Write

Create a Front inbox channel.

Lua path
app.integrations.front.create_channel
Full name
front.front_create_channel
ParameterTypeRequiredDescription
No parameters.
list_inbox_access Read

List teammates with inbox access.

Lua path
app.integrations.front.list_inbox_access
Full name
front.front_list_inbox_access
ParameterTypeRequiredDescription
No parameters.
add_inbox_access Write

Give teammates access to an inbox.

Lua path
app.integrations.front.add_inbox_access
Full name
front.front_add_inbox_access
ParameterTypeRequiredDescription
No parameters.
remove_inbox_access Write

Remove teammate access from an inbox.

Lua path
app.integrations.front.remove_inbox_access
Full name
front.front_remove_inbox_access
ParameterTypeRequiredDescription
No parameters.
list_contacts Read

List Front contacts.

Lua path
app.integrations.front.list_contacts
Full name
front.front_list_contacts
ParameterTypeRequiredDescription
No parameters.
get_contact Read

Get a Front contact.

Lua path
app.integrations.front.get_contact
Full name
front.front_get_contact
ParameterTypeRequiredDescription
No parameters.
create_contact Write

Create a Front contact.

Lua path
app.integrations.front.create_contact
Full name
front.front_create_contact
ParameterTypeRequiredDescription
No parameters.
create_teammate_contact Write

Create a teammate contact.

Lua path
app.integrations.front.create_teammate_contact
Full name
front.front_create_teammate_contact
ParameterTypeRequiredDescription
No parameters.
update_contact Write

Update a Front contact.

Lua path
app.integrations.front.update_contact
Full name
front.front_update_contact
ParameterTypeRequiredDescription
No parameters.
delete_contact Write

Delete a Front contact.

Lua path
app.integrations.front.delete_contact
Full name
front.front_delete_contact
ParameterTypeRequiredDescription
No parameters.
add_contact_handle Write

Add a handle to a Front contact.

Lua path
app.integrations.front.add_contact_handle
Full name
front.front_add_contact_handle
ParameterTypeRequiredDescription
No parameters.
list_contact_conversations Read

List conversations for a contact.

Lua path
app.integrations.front.list_contact_conversations
Full name
front.front_list_contact_conversations
ParameterTypeRequiredDescription
No parameters.
list_team_contacts Read

List contacts for a team.

Lua path
app.integrations.front.list_team_contacts
Full name
front.front_list_team_contacts
ParameterTypeRequiredDescription
No parameters.
list_teammate_contacts Read

List contacts for a teammate.

Lua path
app.integrations.front.list_teammate_contacts
Full name
front.front_list_teammate_contacts
ParameterTypeRequiredDescription
No parameters.
list_teammates Read

List Front teammates.

Lua path
app.integrations.front.list_teammates
Full name
front.front_list_teammates
ParameterTypeRequiredDescription
No parameters.
get_teammate Read

Get a Front teammate.

Lua path
app.integrations.front.get_teammate
Full name
front.front_get_teammate
ParameterTypeRequiredDescription
No parameters.
update_teammate Write

Update a Front teammate.

Lua path
app.integrations.front.update_teammate
Full name
front.front_update_teammate
ParameterTypeRequiredDescription
No parameters.
list_assigned_conversations Read

List conversations assigned to a teammate.

Lua path
app.integrations.front.list_assigned_conversations
Full name
front.front_list_assigned_conversations
ParameterTypeRequiredDescription
No parameters.
list_teammate_inboxes Read

List inboxes for a teammate.

Lua path
app.integrations.front.list_teammate_inboxes
Full name
front.front_list_teammate_inboxes
ParameterTypeRequiredDescription
No parameters.
list_teammate_rules Read

List rules for a teammate.

Lua path
app.integrations.front.list_teammate_rules
Full name
front.front_list_teammate_rules
ParameterTypeRequiredDescription
No parameters.
list_teams Read

List Front teams or workspaces.

Lua path
app.integrations.front.list_teams
Full name
front.front_list_teams
ParameterTypeRequiredDescription
No parameters.
get_team Read

Get a Front team.

Lua path
app.integrations.front.get_team
Full name
front.front_get_team
ParameterTypeRequiredDescription
No parameters.
list_team_inboxes Read

List inboxes for a team.

Lua path
app.integrations.front.list_team_inboxes
Full name
front.front_list_team_inboxes
ParameterTypeRequiredDescription
No parameters.
create_team_inbox Write

Create an inbox for a team.

Lua path
app.integrations.front.create_team_inbox
Full name
front.front_create_team_inbox
ParameterTypeRequiredDescription
No parameters.
list_team_rules Read

List rules for a team.

Lua path
app.integrations.front.list_team_rules
Full name
front.front_list_team_rules
ParameterTypeRequiredDescription
No parameters.
list_tags Read

List Front tags.

Lua path
app.integrations.front.list_tags
Full name
front.front_list_tags
ParameterTypeRequiredDescription
No parameters.
get_tag Read

Get a Front tag.

Lua path
app.integrations.front.get_tag
Full name
front.front_get_tag
ParameterTypeRequiredDescription
No parameters.
create_tag Write

Create a legacy Front tag.

Lua path
app.integrations.front.create_tag
Full name
front.front_create_tag
ParameterTypeRequiredDescription
No parameters.
create_company_tag Write

Create a company tag.

Lua path
app.integrations.front.create_company_tag
Full name
front.front_create_company_tag
ParameterTypeRequiredDescription
No parameters.
create_team_tag Write

Create a team tag.

Lua path
app.integrations.front.create_team_tag
Full name
front.front_create_team_tag
ParameterTypeRequiredDescription
No parameters.
create_teammate_tag Write

Create a teammate tag.

Lua path
app.integrations.front.create_teammate_tag
Full name
front.front_create_teammate_tag
ParameterTypeRequiredDescription
No parameters.
update_tag Write

Update a Front tag.

Lua path
app.integrations.front.update_tag
Full name
front.front_update_tag
ParameterTypeRequiredDescription
No parameters.
delete_tag Write

Delete a Front tag.

Lua path
app.integrations.front.delete_tag
Full name
front.front_delete_tag
ParameterTypeRequiredDescription
No parameters.
list_tagged_conversations Read

List conversations for a tag.

Lua path
app.integrations.front.list_tagged_conversations
Full name
front.front_list_tagged_conversations
ParameterTypeRequiredDescription
No parameters.
list_company_tags Read

List company tags.

Lua path
app.integrations.front.list_company_tags
Full name
front.front_list_company_tags
ParameterTypeRequiredDescription
No parameters.
list_team_tags Read

List team tags.

Lua path
app.integrations.front.list_team_tags
Full name
front.front_list_team_tags
ParameterTypeRequiredDescription
No parameters.
list_teammate_tags Read

List teammate tags.

Lua path
app.integrations.front.list_teammate_tags
Full name
front.front_list_teammate_tags
ParameterTypeRequiredDescription
No parameters.