Can I use Capsule CRM as a CLI?

Yes. KosmoKrator exposes a Capsule CRM CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Capsule CRM through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Capsule CRM tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Capsule CRM credentials stored?

Capsule CRM credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Capsule CRM MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Capsule CRM Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.capsule.api_delete({path = "example_path", query = "example_query"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("capsule"))' --json
kosmo integrations:lua --eval 'print(docs.read("capsule.api_delete"))' --json

Workflow file

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

workflow.lua

local capsule = app.integrations.capsule
local result = capsule.api_delete({path = "example_path", query = "example_query"})

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

MCP-only Lua

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

Capsule CRM Lua API Reference

Namespace: app.integrations.capsule

Capsule CRM tools use the v2 REST API. The integration returns the JSON shape that Capsule returns, usually wrapped in keys such as party, parties, opportunity, opportunities, kase, kases, task, tasks, tags, or definitions.

Parties

Parties are Capsule contacts and organisations.

local parties = app.integrations.capsule.list_contacts({
  page = 1,
  per_page = 50
})

local party = app.integrations.capsule.get_contact({ id = 123 })

app.integrations.capsule.create_contact({
  type = "person",
  firstName = "Jane",
  lastName = "Doe",
  emailAddresses = {
    { address = "jane@example.test" }
  }
})

app.integrations.capsule.update_contact({
  id = 123,
  party = {
    firstName = "Janet"
  }
})

Opportunities

local opportunities = app.integrations.capsule.list_opportunities({
  status = "OPEN",
  page = 1,
  per_page = 100
})

local party_opportunities = app.integrations.capsule.list_party_opportunities({
  party_id = 123,
  params = { embed = "party,milestone,tags,fields" }
})

app.integrations.capsule.create_opportunity({
  opportunity = {
    name = "New deal",
    party = { id = 123 },
    value = { amount = 25000, currency = "USD" }
  }
})

Cases

Capsule calls projects “kases” in the API path.

local cases = app.integrations.capsule.list_cases({
  params = { page = 1, perPage = 50, embed = "party,tags,fields" }
})

app.integrations.capsule.create_case({
  kase = {
    name = "Implementation",
    party = { id = 123 }
  }
})

Tasks

local tasks = app.integrations.capsule.list_tasks({
  status = "OPEN",
  page = 1,
  per_page = 50
})

app.integrations.capsule.create_task({
  task = {
    description = "Follow up",
    dueOn = "2026-05-15"
  }
})

Tracks, Tags, And Custom Fields

Tags and custom fields use an entity argument. Valid entity values are parties, opportunities, and kases; aliases such as contacts, cases, and projects are normalized.

local tracks = app.integrations.capsule.list_tracks({})

local tags = app.integrations.capsule.list_tags({
  entity = "parties"
})

local fields = app.integrations.capsule.list_custom_fields({
  entity = "opportunities"
})

Use tag and field mutation tools only when managing account schema, not when adding values to a record. To add tag or custom field values to a party, opportunity, or case, update that record with the correct Capsule payload.

Raw API Helpers

Use api_get, api_post, api_put, and api_delete for relative paths below the configured Capsule API v2 base URL. Full URLs and parent-directory paths are rejected.

local response = app.integrations.capsule.api_get({
  path = "/parties",
  query = { q = "Acme" }
})

Multi-Account

app.integrations.capsule.production.list_contacts({})
app.integrations.capsule.staging.list_contacts({})

Raw agent markdown

# Capsule CRM Lua API Reference

Namespace: `app.integrations.capsule`

Capsule CRM tools use the v2 REST API. The integration returns the JSON shape that Capsule returns, usually wrapped in keys such as `party`, `parties`, `opportunity`, `opportunities`, `kase`, `kases`, `task`, `tasks`, `tags`, or `definitions`.

## Parties

Parties are Capsule contacts and organisations.

```lua
local parties = app.integrations.capsule.list_contacts({
  page = 1,
  per_page = 50
})

local party = app.integrations.capsule.get_contact({ id = 123 })

app.integrations.capsule.create_contact({
  type = "person",
  firstName = "Jane",
  lastName = "Doe",
  emailAddresses = {
    { address = "jane@example.test" }
  }
})

app.integrations.capsule.update_contact({
  id = 123,
  party = {
    firstName = "Janet"
  }
})
```

## Opportunities

```lua
local opportunities = app.integrations.capsule.list_opportunities({
  status = "OPEN",
  page = 1,
  per_page = 100
})

local party_opportunities = app.integrations.capsule.list_party_opportunities({
  party_id = 123,
  params = { embed = "party,milestone,tags,fields" }
})

app.integrations.capsule.create_opportunity({
  opportunity = {
    name = "New deal",
    party = { id = 123 },
    value = { amount = 25000, currency = "USD" }
  }
})
```

## Cases

Capsule calls projects "kases" in the API path.

```lua
local cases = app.integrations.capsule.list_cases({
  params = { page = 1, perPage = 50, embed = "party,tags,fields" }
})

app.integrations.capsule.create_case({
  kase = {
    name = "Implementation",
    party = { id = 123 }
  }
})
```

## Tasks

```lua
local tasks = app.integrations.capsule.list_tasks({
  status = "OPEN",
  page = 1,
  per_page = 50
})

app.integrations.capsule.create_task({
  task = {
    description = "Follow up",
    dueOn = "2026-05-15"
  }
})
```

## Tracks, Tags, And Custom Fields

Tags and custom fields use an `entity` argument. Valid entity values are `parties`, `opportunities`, and `kases`; aliases such as `contacts`, `cases`, and `projects` are normalized.

```lua
local tracks = app.integrations.capsule.list_tracks({})

local tags = app.integrations.capsule.list_tags({
  entity = "parties"
})

local fields = app.integrations.capsule.list_custom_fields({
  entity = "opportunities"
})
```

Use tag and field mutation tools only when managing account schema, not when adding values to a record. To add tag or custom field values to a party, opportunity, or case, update that record with the correct Capsule payload.

## Raw API Helpers

Use `api_get`, `api_post`, `api_put`, and `api_delete` for relative paths below the configured Capsule API v2 base URL. Full URLs and parent-directory paths are rejected.

```lua
local response = app.integrations.capsule.api_get({
  path = "/parties",
  query = { q = "Acme" }
})
```

## Multi-Account

```lua
app.integrations.capsule.production.list_contacts({})
app.integrations.capsule.staging.list_contacts({})
```

Metadata-derived Lua example

local result = app.integrations.capsule.api_delete({path = "example_path", query = "example_query"})
print(result)

Functions

api_delete Read

Call a safe relative Capsule CRM API path with DELETE for endpoints not covered by a dedicated tool.

Lua path: app.integrations.capsule.api_delete
Full name: capsule.capsule_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative API path below /api/v2.
`query`	object	no	Optional query parameters.

api_get Read

Call a safe relative Capsule CRM API path with GET for endpoints not covered by a dedicated tool.

Lua path: app.integrations.capsule.api_get
Full name: capsule.capsule_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative API path below /api/v2.
`query`	object	no	Optional query parameters.

api_post Read

Call a safe relative Capsule CRM API path with POST for endpoints not covered by a dedicated tool.

Lua path: app.integrations.capsule.api_post
Full name: capsule.capsule_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative API path below /api/v2.
`payload`	object	no	JSON request body.
`query`	object	no	Optional query parameters.

api_put Read

Call a safe relative Capsule CRM API path with PUT for endpoints not covered by a dedicated tool.

Lua path: app.integrations.capsule.api_put
Full name: capsule.capsule_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative API path below /api/v2.
`payload`	object	no	JSON request body.
`query`	object	no	Optional query parameters.

create_case Write

Create a Capsule CRM project/case.

Lua path: app.integrations.capsule.create_case
Full name: capsule.capsule_create_case

Parameter	Type	Required	Description
`kase`	object	yes	Case payload.

create_contact Write

Create a new contact (person or organisation) in Capsule CRM. Provide at least a first name and last name for a person contact.

Lua path: app.integrations.capsule.create_contact
Full name: capsule.capsule_create_contact

Parameter	Type	Required	Description
`type`	string	no	Contact type: "person" (default) or "organisation".
`firstName`	string	yes	First name of the contact.
`lastName`	string	yes	Last name of the contact.
`emailAddresses`	array	no	Email addresses, e.g. [{"address":"user@example.com"}].

create_custom_field Write

Create a custom field definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.create_custom_field
Full name: capsule.capsule_create_custom_field

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`definition`	object	yes	Custom field definition payload.

create_opportunity Write

Create a Capsule CRM sales opportunity.

Lua path: app.integrations.capsule.create_opportunity
Full name: capsule.capsule_create_opportunity

Parameter	Type	Required	Description
`opportunity`	object	yes	Opportunity payload.

create_tag Write

Create a tag definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.create_tag
Full name: capsule.capsule_create_tag

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`tag`	object	yes	Tag payload.

create_task Write

Create a Capsule CRM task.

Lua path: app.integrations.capsule.create_task
Full name: capsule.capsule_create_task

Parameter	Type	Required	Description
`task`	object	yes	Task payload.

delete_case Write

Delete a Capsule CRM project/case.

Lua path: app.integrations.capsule.delete_case
Full name: capsule.capsule_delete_case

Parameter	Type	Required	Description
`id`	integer	yes	Case ID.

delete_contact Write

Delete a Capsule CRM contact or organisation.

Lua path: app.integrations.capsule.delete_contact
Full name: capsule.capsule_delete_contact

Parameter	Type	Required	Description
`id`	integer	yes	Party ID.

delete_custom_field Write

Delete a custom field definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.delete_custom_field
Full name: capsule.capsule_delete_custom_field

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`definition_id`	integer	yes	Definition ID.

delete_opportunity Write

Delete a Capsule CRM opportunity.

Lua path: app.integrations.capsule.delete_opportunity
Full name: capsule.capsule_delete_opportunity

Parameter	Type	Required	Description
`id`	integer	yes	Opportunity ID.

delete_tag Write

Delete a tag definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.delete_tag
Full name: capsule.capsule_delete_tag

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`tag_id`	integer	yes	Tag ID.

delete_task Write

Delete a Capsule CRM task.

Lua path: app.integrations.capsule.delete_task
Full name: capsule.capsule_delete_task

Parameter	Type	Required	Description
`id`	integer	yes	Task ID.

get_case Read

Get one Capsule CRM project/case by ID.

Lua path: app.integrations.capsule.get_case
Full name: capsule.capsule_get_case

Parameter	Type	Required	Description
`id`	integer	yes	Case ID.
`params`	object	no	Optional query parameters such as embed.

get_contact Read

Retrieve a single contact (person or organisation) from Capsule CRM by ID.

Lua path: app.integrations.capsule.get_contact
Full name: capsule.capsule_get_contact

Parameter	Type	Required	Description
`id`	integer	yes	The contact (party) ID.

get_current_user Read

Get the currently authenticated Capsule CRM user. Use this to verify credentials or identify the connected account.

Lua path: app.integrations.capsule.get_current_user
Full name: capsule.capsule_get_current_user

Parameter	Type	Required	Description
No parameters.

get_opportunity Read

Retrieve a single sales opportunity from Capsule CRM by ID.

Lua path: app.integrations.capsule.get_opportunity
Full name: capsule.capsule_get_opportunity

Parameter	Type	Required	Description
`id`	integer	yes	The opportunity ID.

get_task Read

Get one Capsule CRM task by ID.

Lua path: app.integrations.capsule.get_task
Full name: capsule.capsule_get_task

Parameter	Type	Required	Description
`id`	integer	yes	Task ID.

list_cases Read

List Capsule CRM projects/cases.

Lua path: app.integrations.capsule.list_cases
Full name: capsule.capsule_list_cases

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters such as page, perPage, q, since, status, and embed.

list_contacts Read

List contacts (people and organisations) from Capsule CRM. Returns paginated results with contact details.

Lua path: app.integrations.capsule.list_contacts
Full name: capsule.capsule_list_contacts

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of contacts per page, max 100 (default: 50).

list_custom_fields Read

List custom field definitions for parties, opportunities, or cases.

Lua path: app.integrations.capsule.list_custom_fields
Full name: capsule.capsule_list_custom_fields

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`params`	object	no	Optional query parameters.

list_opportunities Read

List sales opportunities from Capsule CRM. Optionally filter by status (OPEN, WON, LOST, CLOSED). Returns paginated results.

Lua path: app.integrations.capsule.list_opportunities
Full name: capsule.capsule_list_opportunities

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of opportunities per page, max 100 (default: 50).
`status`	string	no	Filter by status: OPEN, WON, LOST, or CLOSED.

list_party_cases Read

List projects/cases associated with a Capsule CRM party.

Lua path: app.integrations.capsule.list_party_cases
Full name: capsule.capsule_list_party_cases

Parameter	Type	Required	Description
`party_id`	integer	yes	Party ID.
`params`	object	no	Optional query parameters.

list_party_opportunities Read

List opportunities associated with a Capsule CRM party.

Lua path: app.integrations.capsule.list_party_opportunities
Full name: capsule.capsule_list_party_opportunities

Parameter	Type	Required	Description
`party_id`	integer	yes	Party ID.
`params`	object	no	Optional query parameters such as page, perPage, and embed.

list_tags Read

List tag definitions for parties, opportunities, or cases.

Lua path: app.integrations.capsule.list_tags
Full name: capsule.capsule_list_tags

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`params`	object	no	Optional query parameters.

list_tasks Read

List tasks from Capsule CRM. Optionally filter by status (OPEN, COMPLETED). Returns paginated results.

Lua path: app.integrations.capsule.list_tasks
Full name: capsule.capsule_list_tasks

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`per_page`	integer	no	Number of tasks per page, max 100 (default: 50).
`status`	string	no	Filter by status: OPEN or COMPLETED.

list_tracks Read

List Capsule CRM track definitions for opportunities and cases.

Lua path: app.integrations.capsule.list_tracks
Full name: capsule.capsule_list_tracks

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters.

update_case Write

Update a Capsule CRM project/case.

Lua path: app.integrations.capsule.update_case
Full name: capsule.capsule_update_case

Parameter	Type	Required	Description
`id`	integer	yes	Case ID.
`kase`	object	yes	Case update payload.

update_contact Write

Update a Capsule CRM contact or organisation using a native party payload.

Lua path: app.integrations.capsule.update_contact
Full name: capsule.capsule_update_contact

Parameter	Type	Required	Description
`id`	integer	yes	Party ID.
`party`	object	yes	Party update payload.

update_custom_field Write

Update a custom field definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.update_custom_field
Full name: capsule.capsule_update_custom_field

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`definition_id`	integer	yes	Definition ID.
`definition`	object	yes	Custom field definition update payload.

update_opportunity Write

Update a Capsule CRM sales opportunity.

Lua path: app.integrations.capsule.update_opportunity
Full name: capsule.capsule_update_opportunity

Parameter	Type	Required	Description
`id`	integer	yes	Opportunity ID.
`opportunity`	object	yes	Opportunity update payload.

update_tag Write

Update a tag definition for parties, opportunities, or cases.

Lua path: app.integrations.capsule.update_tag
Full name: capsule.capsule_update_tag

Parameter	Type	Required	Description
`entity`	string	yes	parties, opportunities, or kases.
`tag_id`	integer	yes	Tag ID.
`tag`	object	yes	Tag update payload.

update_task Write

Update a Capsule CRM task.

Lua path: app.integrations.capsule.update_task
Full name: capsule.capsule_update_task

Parameter	Type	Required	Description
`id`	integer	yes	Task ID.
`task`	object	yes	Task update payload.