KosmoKrator

productivity

Immigrant Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local immigrant = app.integrations.immigrant
local result = immigrant.list_applications({limit = 1, 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.immigrant, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.immigrant.default.* or app.integrations.immigrant.work.* when you configured named credential accounts.

MCP-only Lua

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

Immigrant — Lua API Reference

list_applications

List immigration applications.

Parameters

NameTypeRequiredDescription
limitintegernoNumber of applications per page (default: 25, max: 100)
pageintegernoPage number for pagination (1-based)
statusstringnoFilter by status (e.g. “pending”, “approved”, “rejected”)

Examples

-- List pending applications
local result = app.integrations.immigrant.list_applications({
  status = "pending",
  limit = 10
})

for _, app in ipairs(result) do
  print(app.id .. ": " .. app.applicant_name .. " [" .. app.status .. "]")
end
-- Paginate through all applications
local page1 = app.integrations.immigrant.list_applications({ limit = 50, page = 1 })
local page2 = app.integrations.immigrant.list_applications({ limit = 50, page = 2 })

get_application

Get details of a specific immigration application.

Parameters

NameTypeRequiredDescription
idstringyesThe Immigrant application ID

Examples

local application = app.integrations.immigrant.get_application({ id = "app_abc123" })
print(application.applicant_name)
print(application.type)
print("Status: " .. application.status)

create_application

Create a new immigration application.

Parameters

NameTypeRequiredDescription
typestringyesApplication type (e.g. “visa”, “green_card”, “citizenship”)
applicant_namestringyesFull name of the applicant
detailsobjectnoAdditional application details (key-value pairs)

Examples

-- Create a basic visa application
local application = app.integrations.immigrant.create_application({
  type = "visa",
  applicant_name = "Jane Doe"
})

print("Created application #" .. application.id)
-- Create an application with details
local application = app.integrations.immigrant.create_application({
  type = "green_card",
  applicant_name = "John Smith",
  details = {
    country_of_origin = "Canada",
    current_visa_type = "H1B",
    employer = "Acme Corp"
  }
})

list_documents

List documents for a specific immigration application.

Parameters

NameTypeRequiredDescription
application_idstringyesThe Immigrant application ID
limitintegernoNumber of documents per page (default: 25, max: 100)
pageintegernoPage number for pagination (1-based)

Examples

-- List documents for an application
local docs = app.integrations.immigrant.list_documents({
  application_id = "app_abc123",
  limit = 20
})

for _, doc in ipairs(docs) do
  print(doc.id .. ": " .. doc.name .. " (" .. doc.status .. ")")
end

get_document

Get details of a specific document.

Parameters

NameTypeRequiredDescription
idstringyesThe Immigrant document ID

Examples

local doc = app.integrations.immigrant.get_document({ id = "doc_xyz789" })
print(doc.name)
print("Status: " .. doc.status)
print("Uploaded: " .. doc.uploaded_at)

list_statuses

List all available application statuses.

Parameters

None.

Examples

local statuses = app.integrations.immigrant.list_statuses({})

for _, status in ipairs(statuses) do
  print(status.id .. ": " .. status.name .. " - " .. status.description)
end

get_current_user

Get the currently authenticated Immigrant user’s profile.

Parameters

None.

Examples

local user = app.integrations.immigrant.get_current_user({})
print("Logged in as: " .. user.first_name .. " " .. user.last_name)
print("Email: " .. user.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.immigrant.list_applications({})

-- Explicit default (portable across setups)
app.integrations.immigrant.default.list_applications({})

-- Named accounts
app.integrations.immigrant.production.list_applications({})
app.integrations.immigrant.staging.list_applications({})

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

Raw agent markdown 
# Immigrant — Lua API Reference

## list_applications

List immigration applications.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of applications per page (default: 25, max: 100) |
| `page` | integer | no | Page number for pagination (1-based) |
| `status` | string | no | Filter by status (e.g. "pending", "approved", "rejected") |

### Examples

```lua
-- List pending applications
local result = app.integrations.immigrant.list_applications({
  status = "pending",
  limit = 10
})

for _, app in ipairs(result) do
  print(app.id .. ": " .. app.applicant_name .. " [" .. app.status .. "]")
end
```

```lua
-- Paginate through all applications
local page1 = app.integrations.immigrant.list_applications({ limit = 50, page = 1 })
local page2 = app.integrations.immigrant.list_applications({ limit = 50, page = 2 })
```

---

## get_application

Get details of a specific immigration application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Immigrant application ID |

### Examples

```lua
local application = app.integrations.immigrant.get_application({ id = "app_abc123" })
print(application.applicant_name)
print(application.type)
print("Status: " .. application.status)
```

---

## create_application

Create a new immigration application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | yes | Application type (e.g. "visa", "green_card", "citizenship") |
| `applicant_name` | string | yes | Full name of the applicant |
| `details` | object | no | Additional application details (key-value pairs) |

### Examples

```lua
-- Create a basic visa application
local application = app.integrations.immigrant.create_application({
  type = "visa",
  applicant_name = "Jane Doe"
})

print("Created application #" .. application.id)
```

```lua
-- Create an application with details
local application = app.integrations.immigrant.create_application({
  type = "green_card",
  applicant_name = "John Smith",
  details = {
    country_of_origin = "Canada",
    current_visa_type = "H1B",
    employer = "Acme Corp"
  }
})
```

---

## list_documents

List documents for a specific immigration application.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `application_id` | string | yes | The Immigrant application ID |
| `limit` | integer | no | Number of documents per page (default: 25, max: 100) |
| `page` | integer | no | Page number for pagination (1-based) |

### Examples

```lua
-- List documents for an application
local docs = app.integrations.immigrant.list_documents({
  application_id = "app_abc123",
  limit = 20
})

for _, doc in ipairs(docs) do
  print(doc.id .. ": " .. doc.name .. " (" .. doc.status .. ")")
end
```

---

## get_document

Get details of a specific document.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Immigrant document ID |

### Examples

```lua
local doc = app.integrations.immigrant.get_document({ id = "doc_xyz789" })
print(doc.name)
print("Status: " .. doc.status)
print("Uploaded: " .. doc.uploaded_at)
```

---

## list_statuses

List all available application statuses.

### Parameters

None.

### Examples

```lua
local statuses = app.integrations.immigrant.list_statuses({})

for _, status in ipairs(statuses) do
  print(status.id .. ": " .. status.name .. " - " .. status.description)
end
```

---

## get_current_user

Get the currently authenticated Immigrant user's profile.

### Parameters

None.

### Examples

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

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.immigrant.list_applications({})

-- Explicit default (portable across setups)
app.integrations.immigrant.default.list_applications({})

-- Named accounts
app.integrations.immigrant.production.list_applications({})
app.integrations.immigrant.staging.list_applications({})
```

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

Functions

list_applications Read

List immigration applications. Returns a paginated list of applications, optionally filtered by status.

Lua path
app.integrations.immigrant.list_applications
Full name
immigrant.immigrant_list_applications
ParameterTypeRequiredDescription
limit integer no Number of applications to return per page (default: 25, max: 100).
page integer no Page number for pagination (1-based).
status string no Filter applications by status (e.g. "pending", "approved", "rejected").
get_application Read

Get details of a specific immigration application by its ID.

Lua path
app.integrations.immigrant.get_application
Full name
immigrant.immigrant_get_application
ParameterTypeRequiredDescription
id string yes The Immigrant application ID.
create_application Write

Create a new immigration application. Requires a type and applicant name. Optionally provide additional details.

Lua path
app.integrations.immigrant.create_application
Full name
immigrant.immigrant_create_application
ParameterTypeRequiredDescription
type string yes Application type (e.g. "visa", "green_card", "citizenship").
applicant_name string yes Full name of the applicant.
details object no Optional additional application details (key-value pairs).
list_documents Read

List documents for a specific immigration application. Returns a paginated list of documents.

Lua path
app.integrations.immigrant.list_documents
Full name
immigrant.immigrant_list_documents
ParameterTypeRequiredDescription
application_id string yes The Immigrant application ID to list documents for.
limit integer no Number of documents to return per page (default: 25, max: 100).
page integer no Page number for pagination (1-based).
get_document Read

Get details of a specific document by its ID.

Lua path
app.integrations.immigrant.get_document
Full name
immigrant.immigrant_get_document
ParameterTypeRequiredDescription
id string yes The Immigrant document ID.
list_statuses Read

List all available immigration application statuses. Use this to understand valid status values for filtering.

Lua path
app.integrations.immigrant.list_statuses
Full name
immigrant.immigrant_list_statuses
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the profile of the currently authenticated Immigrant user. Use this to verify credentials and see user details.

Lua path
app.integrations.immigrant.get_current_user
Full name
immigrant.immigrant_get_current_user
ParameterTypeRequiredDescription
No parameters.