KosmoKrator

data

Freeagent Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.freeagent.list_invoices({status = "example_status", from_date = "example_from_date", to_date = "example_to_date", contact = "example_contact", project = "example_project", page = 1, per_page = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("freeagent"))' --json
kosmo integrations:lua --eval 'print(docs.read("freeagent.list_invoices"))' --json

Workflow file

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

workflow.lua 
local freeagent = app.integrations.freeagent
local result = freeagent.list_invoices({status = "example_status", from_date = "example_from_date", to_date = "example_to_date", contact = "example_contact", project = "example_project", page = 1, per_page = 1})

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

MCP-only Lua

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

FreeAgent — Lua API Reference

list_invoices

List invoices from FreeAgent.

Parameters

NameTypeRequiredDescription
statusstringnoFilter by status: Draft, Sent, Cancelled, Late, Paid
from_datestringnoStart date (ISO 8601, e.g., "2025-01-01")
to_datestringnoEnd date (ISO 8601, e.g., "2025-12-31")
contactstringnoFilter by contact URL or ID
projectstringnoFilter by project URL or ID
pageintegernoPage number for pagination
per_pageintegernoResults per page (default: 30)

Example

local result = app.integrations.freeagent.list_invoices({
  status = "Sent",
  from_date = "2025-01-01",
  per_page = 50
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.reference .. ": " .. invoice.total .. " " .. invoice.currency)
end

get_invoice

Get full details of a specific invoice.

Parameters

NameTypeRequiredDescription
invoice_idintegeryesThe ID of the invoice

Example

local result = app.integrations.freeagent.get_invoice({
  invoice_id = 12345
})

print("Invoice: " .. result.invoice.reference)
print("Total: " .. result.invoice.total .. " " .. result.invoice.currency)
print("Status: " .. result.invoice.status)

for _, item in ipairs(result.invoice.invoice_items) do
  print("  - " .. item.description .. ": " .. item.price)
end

create_invoice

Create a new invoice in FreeAgent.

Parameters

NameTypeRequiredDescription
contactstringyesContact URL or ID (e.g., "https://api.freeagent.com/v2/contacts/123")
dated_onstringyesInvoice date (ISO 8601)
invoice_itemsarrayyesLine items, each with description, quantity, price
due_onstringnoDue date (ISO 8601)
referencestringnoReference number
currencystringnoCurrency code (GBP, USD, EUR)
commentsstringnoInvoice comments
projectstringnoProject URL to associate

Example

local result = app.integrations.freeagent.create_invoice({
  contact = "https://api.freeagent.com/v2/contacts/123",
  dated_on = "2025-04-01",
  due_on = "2025-04-30",
  reference = "INV-001",
  currency = "GBP",
  invoice_items = {
    { description = "Web development", quantity = 10, price = 75.00 },
    { description = "Hosting setup", quantity = 1, price = 150.00 }
  }
})

print("Created invoice: " .. result.invoice.reference)

list_contacts

List contacts from FreeAgent.

Parameters

NameTypeRequiredDescription
viewstringnoFilter: all, customers, suppliers, active, inactive
orderstringnoSort: name, created_at, updated_at. Prefix - for descending
created_sincestringnoOnly contacts created after this date
updated_sincestringnoOnly contacts updated after this date
pageintegernoPage number
per_pageintegernoResults per page (default: 30)

Example

local result = app.integrations.freeagent.list_contacts({
  view = "customers",
  order = "name",
  per_page = 50
})

for _, contact in ipairs(result.contacts) do
  print(contact.organisation_name or (contact.first_name .. " " .. contact.last_name))
end

get_contact

Get full details of a specific contact.

Parameters

NameTypeRequiredDescription
contact_idintegeryesThe ID of the contact

Example

local result = app.integrations.freeagent.get_contact({
  contact_id = 456
})

local c = result.contact
print(c.organisation_name or (c.first_name .. " " .. c.last_name))
print("Email: " .. (c.email or "N/A"))
print("Type: " .. c.contact_type)

create_contact

Create a new contact in FreeAgent.

Parameters

NameTypeRequiredDescription
first_namestringnoFirst name (for individuals)
last_namestringnoLast name (for individuals)
organisation_namestringnoCompany name (for companies)
emailstringnoPrimary email
phone_numberstringnoPhone number
contact_typestringnoCustomer (default) or Supplier
billing_emailstringnoBilling email
address1stringnoAddress line 1
address2stringnoAddress line 2
townstringnoTown or city
regionstringnoState or province
postcodestringnoPostal code
countrystringnoCountry code (e.g., GB, US, NL)

At least one of first_name, last_name, or organisation_name is required.

Example

local result = app.integrations.freeagent.create_contact({
  organisation_name = "Acme Corp",
  email = "billing@acme.com",
  contact_type = "Customer",
  country = "GB"
})

print("Created contact: " .. result.contact.organisation_name)

list_projects

List projects from FreeAgent.

Parameters

NameTypeRequiredDescription
viewstringnoFilter: all, active, completed, cancelled, unquoted
contactstringnoFilter by contact URL or ID
pageintegernoPage number
per_pageintegernoResults per page (default: 30)

Example

local result = app.integrations.freeagent.list_projects({
  view = "active"
})

for _, project in ipairs(result.projects) do
  print(project.name .. " (" .. project.status .. ")")
  print("  Budget: " .. project.budget .. " " .. project.currency)
end

list_expenses

List expenses from FreeAgent.

Parameters

NameTypeRequiredDescription
from_datestringnoStart date (ISO 8601)
to_datestringnoEnd date (ISO 8601)
contactstringnoFilter by contact URL or ID
projectstringnoFilter by project URL or ID
pageintegernoPage number
per_pageintegernoResults per page (default: 30)

Example

local result = app.integrations.freeagent.list_expenses({
  from_date = "2025-01-01",
  to_date = "2025-03-31",
  per_page = 100
})

for _, expense in ipairs(result.expenses) do
  print(expense.description .. ": " .. expense.total .. " " .. expense.currency)
end

get_current_user

Get the currently authenticated FreeAgent user.

Parameters

None.

Example

local result = app.integrations.freeagent.get_current_user({})

local user = result.user
print("Name: " .. user.first_name .. " " .. user.last_name)
print("Email: " .. user.email)
print("Role: " .. user.role)

Multi-Account Usage

If you have multiple FreeAgent accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.freeagent.list_invoices({...})

-- Explicit default (portable across setups)
app.integrations.freeagent.default.list_invoices({...})

-- Named accounts
app.integrations.freeagent.uk.list_invoices({...})
app.integrations.freeagent.us.list_invoices({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# FreeAgent — Lua API Reference

## list_invoices

List invoices from FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | no | Filter by status: `Draft`, `Sent`, `Cancelled`, `Late`, `Paid` |
| `from_date` | string | no | Start date (ISO 8601, e.g., `"2025-01-01"`) |
| `to_date` | string | no | End date (ISO 8601, e.g., `"2025-12-31"`) |
| `contact` | string | no | Filter by contact URL or ID |
| `project` | string | no | Filter by project URL or ID |
| `page` | integer | no | Page number for pagination |
| `per_page` | integer | no | Results per page (default: 30) |

### Example

```lua
local result = app.integrations.freeagent.list_invoices({
  status = "Sent",
  from_date = "2025-01-01",
  per_page = 50
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.reference .. ": " .. invoice.total .. " " .. invoice.currency)
end
```

---

## get_invoice

Get full details of a specific invoice.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `invoice_id` | integer | yes | The ID of the invoice |

### Example

```lua
local result = app.integrations.freeagent.get_invoice({
  invoice_id = 12345
})

print("Invoice: " .. result.invoice.reference)
print("Total: " .. result.invoice.total .. " " .. result.invoice.currency)
print("Status: " .. result.invoice.status)

for _, item in ipairs(result.invoice.invoice_items) do
  print("  - " .. item.description .. ": " .. item.price)
end
```

---

## create_invoice

Create a new invoice in FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contact` | string | yes | Contact URL or ID (e.g., `"https://api.freeagent.com/v2/contacts/123"`) |
| `dated_on` | string | yes | Invoice date (ISO 8601) |
| `invoice_items` | array | yes | Line items, each with `description`, `quantity`, `price` |
| `due_on` | string | no | Due date (ISO 8601) |
| `reference` | string | no | Reference number |
| `currency` | string | no | Currency code (`GBP`, `USD`, `EUR`) |
| `comments` | string | no | Invoice comments |
| `project` | string | no | Project URL to associate |

### Example

```lua
local result = app.integrations.freeagent.create_invoice({
  contact = "https://api.freeagent.com/v2/contacts/123",
  dated_on = "2025-04-01",
  due_on = "2025-04-30",
  reference = "INV-001",
  currency = "GBP",
  invoice_items = {
    { description = "Web development", quantity = 10, price = 75.00 },
    { description = "Hosting setup", quantity = 1, price = 150.00 }
  }
})

print("Created invoice: " .. result.invoice.reference)
```

---

## list_contacts

List contacts from FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `view` | string | no | Filter: `all`, `customers`, `suppliers`, `active`, `inactive` |
| `order` | string | no | Sort: `name`, `created_at`, `updated_at`. Prefix `-` for descending |
| `created_since` | string | no | Only contacts created after this date |
| `updated_since` | string | no | Only contacts updated after this date |
| `page` | integer | no | Page number |
| `per_page` | integer | no | Results per page (default: 30) |

### Example

```lua
local result = app.integrations.freeagent.list_contacts({
  view = "customers",
  order = "name",
  per_page = 50
})

for _, contact in ipairs(result.contacts) do
  print(contact.organisation_name or (contact.first_name .. " " .. contact.last_name))
end
```

---

## get_contact

Get full details of a specific contact.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contact_id` | integer | yes | The ID of the contact |

### Example

```lua
local result = app.integrations.freeagent.get_contact({
  contact_id = 456
})

local c = result.contact
print(c.organisation_name or (c.first_name .. " " .. c.last_name))
print("Email: " .. (c.email or "N/A"))
print("Type: " .. c.contact_type)
```

---

## create_contact

Create a new contact in FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `first_name` | string | no | First name (for individuals) |
| `last_name` | string | no | Last name (for individuals) |
| `organisation_name` | string | no | Company name (for companies) |
| `email` | string | no | Primary email |
| `phone_number` | string | no | Phone number |
| `contact_type` | string | no | `Customer` (default) or `Supplier` |
| `billing_email` | string | no | Billing email |
| `address1` | string | no | Address line 1 |
| `address2` | string | no | Address line 2 |
| `town` | string | no | Town or city |
| `region` | string | no | State or province |
| `postcode` | string | no | Postal code |
| `country` | string | no | Country code (e.g., `GB`, `US`, `NL`) |

> At least one of `first_name`, `last_name`, or `organisation_name` is required.

### Example

```lua
local result = app.integrations.freeagent.create_contact({
  organisation_name = "Acme Corp",
  email = "billing@acme.com",
  contact_type = "Customer",
  country = "GB"
})

print("Created contact: " .. result.contact.organisation_name)
```

---

## list_projects

List projects from FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `view` | string | no | Filter: `all`, `active`, `completed`, `cancelled`, `unquoted` |
| `contact` | string | no | Filter by contact URL or ID |
| `page` | integer | no | Page number |
| `per_page` | integer | no | Results per page (default: 30) |

### Example

```lua
local result = app.integrations.freeagent.list_projects({
  view = "active"
})

for _, project in ipairs(result.projects) do
  print(project.name .. " (" .. project.status .. ")")
  print("  Budget: " .. project.budget .. " " .. project.currency)
end
```

---

## list_expenses

List expenses from FreeAgent.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from_date` | string | no | Start date (ISO 8601) |
| `to_date` | string | no | End date (ISO 8601) |
| `contact` | string | no | Filter by contact URL or ID |
| `project` | string | no | Filter by project URL or ID |
| `page` | integer | no | Page number |
| `per_page` | integer | no | Results per page (default: 30) |

### Example

```lua
local result = app.integrations.freeagent.list_expenses({
  from_date = "2025-01-01",
  to_date = "2025-03-31",
  per_page = 100
})

for _, expense in ipairs(result.expenses) do
  print(expense.description .. ": " .. expense.total .. " " .. expense.currency)
end
```

---

## get_current_user

Get the currently authenticated FreeAgent user.

### Parameters

None.

### Example

```lua
local result = app.integrations.freeagent.get_current_user({})

local user = result.user
print("Name: " .. user.first_name .. " " .. user.last_name)
print("Email: " .. user.email)
print("Role: " .. user.role)
```

---

## Multi-Account Usage

If you have multiple FreeAgent accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.freeagent.list_invoices({...})

-- Explicit default (portable across setups)
app.integrations.freeagent.default.list_invoices({...})

-- Named accounts
app.integrations.freeagent.uk.list_invoices({...})
app.integrations.freeagent.us.list_invoices({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.freeagent.list_invoices({status = "example_status", from_date = "example_from_date", to_date = "example_to_date", contact = "example_contact", project = "example_project", page = 1, per_page = 1})
print(result)

Functions

list_invoices Read

List invoices from FreeAgent. Returns a paginated list of invoices with their details. Supports filtering by status (Draft, Sent, Cancelled, Late Paid, Paid), date range, contact, and project.

Lua path
app.integrations.freeagent.list_invoices
Full name
freeagent.freeagent_list_invoices
ParameterTypeRequiredDescription
status string no Filter by status: Draft, Sent, Cancelled, Late, Paid.
from_date string no Start date for filtering (ISO 8601, e.g., "2025-01-01").
to_date string no End date for filtering (ISO 8601, e.g., "2025-12-31").
contact string no Filter by contact URL or ID.
project string no Filter by project URL or ID.
page integer no Page number for pagination.
per_page integer no Number of results per page (default: 30).
get_invoice Read

Get the full details of a specific invoice from FreeAgent, including line items, totals, contact information, and status.

Lua path
app.integrations.freeagent.get_invoice
Full name
freeagent.freeagent_get_invoice
ParameterTypeRequiredDescription
invoice_id integer yes The ID of the invoice to retrieve.
create_invoice Write

Create a new invoice in FreeAgent. Requires a contact and at least one line item. Supports setting due date, currency, invoice items with quantities and prices, and comments.

Lua path
app.integrations.freeagent.create_invoice
Full name
freeagent.freeagent_create_invoice
ParameterTypeRequiredDescription
contact string yes The contact URL or ID for the invoice recipient (e.g., "https://api.freeagent.com/v2/contacts/123").
dated_on string yes The invoice date (ISO 8601, e.g., "2025-01-15").
invoice_items array yes Array of line items, each with "description", "quantity", and "price". Optionally include "sales_tax_rate".
due_on string no The due date (ISO 8601). If omitted, FreeAgent calculates based on contact terms.
reference string no A reference number for the invoice.
currency string no Currency code (e.g., "GBP", "USD", "EUR"). Defaults to the company currency.
comments string no Comments or notes to include on the invoice.
project string no The project URL to associate the invoice with.
list_contacts Read

List contacts from FreeAgent. Returns a paginated list of contacts including customers, suppliers, and employees. Supports filtering and sorting.

Lua path
app.integrations.freeagent.list_contacts
Full name
freeagent.freeagent_list_contacts
ParameterTypeRequiredDescription
view string no Filter view: "all" (default), "customers", "suppliers", "active", "inactive".
order string no Sort order: "name", "created_at", "updated_at". Prefix with "-" for descending.
created_since string no Only contacts created after this date (ISO 8601).
updated_since string no Only contacts updated after this date (ISO 8601).
page integer no Page number for pagination.
per_page integer no Number of results per page (default: 30).
get_contact Read

Get the full details of a specific contact from FreeAgent, including name, email, company, billing address, and contact type.

Lua path
app.integrations.freeagent.get_contact
Full name
freeagent.freeagent_get_contact
ParameterTypeRequiredDescription
contact_id integer yes The ID of the contact to retrieve.
create_contact Write

Create a new contact in FreeAgent. Contacts can be customers, suppliers, or employees. Provide at least a name (first_name/last_name for individuals or organisation_name for companies).

Lua path
app.integrations.freeagent.create_contact
Full name
freeagent.freeagent_create_contact
ParameterTypeRequiredDescription
first_name string no First name (for individual contacts).
last_name string no Last name (for individual contacts).
organisation_name string no Company or organisation name (for company contacts).
email string no Primary email address.
phone_number string no Phone number.
contact_type string no Contact type: "Customer" (default) or "Supplier".
billing_email string no Email address for invoicing.
address1 string no Address line 1.
address2 string no Address line 2.
town string no Town or city.
region string no Region, state, or province.
postcode string no Postal or ZIP code.
country string no Country code (e.g., "GB", "US", "NL").
list_projects Read

List projects from FreeAgent. Returns project names, status, budget, associated contacts, and time tracking information.

Lua path
app.integrations.freeagent.list_projects
Full name
freeagent.freeagent_list_projects
ParameterTypeRequiredDescription
view string no Filter view: "all" (default), "active", "completed", "cancelled", "unquoted".
contact string no Filter by contact URL or ID.
page integer no Page number for pagination.
per_page integer no Number of results per page (default: 30).
list_expenses Read

List expenses from FreeAgent. Returns expense claims with amounts, categories, dates, and associated projects or contacts.

Lua path
app.integrations.freeagent.list_expenses
Full name
freeagent.freeagent_list_expenses
ParameterTypeRequiredDescription
from_date string no Start date for filtering (ISO 8601, e.g., "2025-01-01").
to_date string no End date for filtering (ISO 8601, e.g., "2025-12-31").
contact string no Filter by contact URL or ID.
project string no Filter by project URL or ID.
page integer no Page number for pagination.
per_page integer no Number of results per page (default: 30).
get_current_user Read

Get the currently authenticated FreeAgent user profile. Returns user details like name, email, role, and company information. Useful for verifying the connection and understanding which account is active.

Lua path
app.integrations.freeagent.get_current_user
Full name
freeagent.freeagent_get_current_user
ParameterTypeRequiredDescription
No parameters.