KosmoKrator

productivity

Freshteam Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.freshteam.list_candidates({page = 1, per_page = 1, status = "example_status"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("freshteam"))' --json
kosmo integrations:lua --eval 'print(docs.read("freshteam.list_candidates"))' --json

Workflow file

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

workflow.lua 
local freshteam = app.integrations.freshteam
local result = freshteam.list_candidates({page = 1, per_page = 1, status = "example_status"})

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

MCP-only Lua

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

Freshteam — Lua API Reference

list_candidates

List recruitment candidates with optional status filtering and pagination.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
statusstringnoFilter by status (e.g., "active", "hired", "rejected", "on_hold")

Example

local result = app.integrations.freshteam.list_candidates({
  page = 1,
  per_page = 10,
  status = "active"
})

for _, candidate in ipairs(result) do
  print(candidate.first_name .. " " .. candidate.last_name .. " - " .. candidate.email)
end

get_candidate

Retrieve details for a specific candidate.

Parameters

NameTypeRequiredDescription
idintegeryesThe candidate ID

Example

local candidate = app.integrations.freshteam.get_candidate({ id = 12345 })
print(candidate.first_name .. " " .. candidate.last_name)
print("Email: " .. candidate.email)
print("Status: " .. candidate.status)

list_job_postings

List job postings with optional filtering by status and department.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
statusstringnoFilter by status (e.g., "published", "draft", "closed")
department_idintegernoFilter by department ID

Example

local result = app.integrations.freshteam.list_job_postings({
  page = 1,
  per_page = 10,
  status = "published"
})

for _, job in ipairs(result) do
  print(job.title .. " (" .. job.status .. ")")
end

get_job_posting

Retrieve details for a specific job posting.

Parameters

NameTypeRequiredDescription
idintegeryesThe job posting ID

Example

local job = app.integrations.freshteam.get_job_posting({ id = 67890 })
print(job.title)
print("Department: " .. (job.department and job.department.name or "N/A"))
print("Location: " .. (job.location or "Remote"))

list_employees

List employees with optional department filtering.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
department_idintegernoFilter by department ID

Example

local result = app.integrations.freshteam.list_employees({
  page = 1,
  per_page = 50
})

for _, emp in ipairs(result) do
  print(emp.first_name .. " " .. emp.last_name .. " - " .. (emp.email or ""))
end

get_employee

Retrieve details for a specific employee.

Parameters

NameTypeRequiredDescription
idintegeryesThe employee ID

Example

local emp = app.integrations.freshteam.get_employee({ id = 54321 })
print(emp.first_name .. " " .. emp.last_name)
print("Email: " .. emp.email)
print("Department: " .. (emp.department and emp.department.name or "N/A"))

get_current_user

Retrieve the currently authenticated user’s profile. Useful for verifying the connection.

Parameters

None.

Example

local user = app.integrations.freshteam.get_current_user({})
print("Logged in as: " .. user.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.freshteam.list_candidates({})

-- Explicit default (portable across setups)
app.integrations.freshteam.default.list_candidates({})

-- Named accounts
app.integrations.freshteam.acme.list_candidates({})
app.integrations.freshteam.other_company.list_employees({})

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

Raw agent markdown 
# Freshteam — Lua API Reference

## list_candidates

List recruitment candidates with optional status filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `status` | string | no | Filter by status (e.g., `"active"`, `"hired"`, `"rejected"`, `"on_hold"`) |

### Example

```lua
local result = app.integrations.freshteam.list_candidates({
  page = 1,
  per_page = 10,
  status = "active"
})

for _, candidate in ipairs(result) do
  print(candidate.first_name .. " " .. candidate.last_name .. " - " .. candidate.email)
end
```

---

## get_candidate

Retrieve details for a specific candidate.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The candidate ID |

### Example

```lua
local candidate = app.integrations.freshteam.get_candidate({ id = 12345 })
print(candidate.first_name .. " " .. candidate.last_name)
print("Email: " .. candidate.email)
print("Status: " .. candidate.status)
```

---

## list_job_postings

List job postings with optional filtering by status and department.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `status` | string | no | Filter by status (e.g., `"published"`, `"draft"`, `"closed"`) |
| `department_id` | integer | no | Filter by department ID |

### Example

```lua
local result = app.integrations.freshteam.list_job_postings({
  page = 1,
  per_page = 10,
  status = "published"
})

for _, job in ipairs(result) do
  print(job.title .. " (" .. job.status .. ")")
end
```

---

## get_job_posting

Retrieve details for a specific job posting.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The job posting ID |

### Example

```lua
local job = app.integrations.freshteam.get_job_posting({ id = 67890 })
print(job.title)
print("Department: " .. (job.department and job.department.name or "N/A"))
print("Location: " .. (job.location or "Remote"))
```

---

## list_employees

List employees with optional department filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `department_id` | integer | no | Filter by department ID |

### Example

```lua
local result = app.integrations.freshteam.list_employees({
  page = 1,
  per_page = 50
})

for _, emp in ipairs(result) do
  print(emp.first_name .. " " .. emp.last_name .. " - " .. (emp.email or ""))
end
```

---

## get_employee

Retrieve details for a specific employee.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The employee ID |

### Example

```lua
local emp = app.integrations.freshteam.get_employee({ id = 54321 })
print(emp.first_name .. " " .. emp.last_name)
print("Email: " .. emp.email)
print("Department: " .. (emp.department and emp.department.name or "N/A"))
```

---

## get_current_user

Retrieve the currently authenticated user's profile. Useful for verifying the connection.

### Parameters

None.

### Example

```lua
local user = app.integrations.freshteam.get_current_user({})
print("Logged in as: " .. user.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.freshteam.list_candidates({})

-- Explicit default (portable across setups)
app.integrations.freshteam.default.list_candidates({})

-- Named accounts
app.integrations.freshteam.acme.list_candidates({})
app.integrations.freshteam.other_company.list_employees({})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.freshteam.list_candidates({page = 1, per_page = 1, status = "example_status"})
print(result)

Functions

list_candidates Read

List recruitment candidates from Freshteam. Returns paginated candidate records with optional filtering by status.

Lua path
app.integrations.freshteam.list_candidates
Full name
freshteam.freshteam_list_candidates
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
status string no Filter candidates by status (e.g., "active", "hired", "rejected", "on_hold").
get_candidate Read

Retrieve detailed information about a specific candidate in Freshteam by their ID.

Lua path
app.integrations.freshteam.get_candidate
Full name
freshteam.freshteam_get_candidate
ParameterTypeRequiredDescription
id integer yes The candidate ID.
list_job_postings Read

List job postings from Freshteam. Returns paginated job records with optional filtering by status and department.

Lua path
app.integrations.freshteam.list_job_postings
Full name
freshteam.freshteam_list_job_postings
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
status string no Filter job postings by status (e.g., "published", "draft", "closed", "on_hold").
department_id integer no Filter by department ID.
get_job_posting Read

Retrieve detailed information about a specific job posting in Freshteam by its ID.

Lua path
app.integrations.freshteam.get_job_posting
Full name
freshteam.freshteam_get_job_posting
ParameterTypeRequiredDescription
id integer yes The job posting ID.
list_employees Read

List employees from Freshteam. Returns paginated employee records with optional filtering by department.

Lua path
app.integrations.freshteam.list_employees
Full name
freshteam.freshteam_list_employees
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
department_id integer no Filter by department ID.
get_employee Read

Retrieve detailed information about a specific employee in Freshteam by their ID.

Lua path
app.integrations.freshteam.get_employee
Full name
freshteam.freshteam_get_employee
ParameterTypeRequiredDescription
id integer yes The employee ID.
get_current_user Read

Retrieve the profile of the currently authenticated Freshteam user. Useful for verifying the connection and identifying which account is active.

Lua path
app.integrations.freshteam.get_current_user
Full name
freshteam.freshteam_get_current_user
ParameterTypeRequiredDescription
No parameters.