Can I use Freeagent as a CLI?

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

Can I expose Freeagent through MCP?

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

Where are Freeagent credentials stored?

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

Can I deny write access for Freeagent MCP tools?

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

other

Freeagent Lua API for KosmoKrator Agents

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

9 functions 7 read 2 write Manual OAuth token auth

Submit Freeagent feedback View package source

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.

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

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

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

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

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

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

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

local result = app.integrations.freeagent.create_contact({
  organisation_name = "Acme Corp",
  email = "[email protected]",
  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

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

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 = "[email protected]",
  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.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

`freeagent_list_invoices`

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.

Operation: Read read
Full name: freeagent.freeagent_list_invoices

Parameter	Type	Required	Description
`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).

`freeagent_get_invoice`

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

Operation: Read read
Full name: freeagent.freeagent_get_invoice

Parameter	Type	Required	Description
`invoice_id`	integer	yes	The ID of the invoice to retrieve.

`freeagent_create_invoice`

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.

Operation: Write write
Full name: freeagent.freeagent_create_invoice

Parameter	Type	Required	Description
`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.

`freeagent_list_contacts`

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

Operation: Read read
Full name: freeagent.freeagent_list_contacts

Parameter	Type	Required	Description
`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).

`freeagent_get_contact`

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

Operation: Read read
Full name: freeagent.freeagent_get_contact

Parameter	Type	Required	Description
`contact_id`	integer	yes	The ID of the contact to retrieve.

`freeagent_create_contact`

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).

Operation: Write write
Full name: freeagent.freeagent_create_contact

Parameter	Type	Required	Description
`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").

`freeagent_list_projects`

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

Operation: Read read
Full name: freeagent.freeagent_list_projects

Parameter	Type	Required	Description
`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).

`freeagent_list_expenses`

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

Operation: Read read
Full name: freeagent.freeagent_list_expenses

Parameter	Type	Required	Description
`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).

`freeagent_get_current_user`

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.

Operation: Read read
Full name: freeagent.freeagent_get_current_user

Parameter	Type	Required	Description
No parameters.