KosmoKrator

other

Clerk Lua API for KosmoKrator Agents

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

7 functions 4 read 3 write API key auth
Submit Clerk feedback View package source

Lua Namespace

Agents call this integration through app.integrations.clerk.*. Use lua_read_doc("integrations.clerk") 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.

Clerk — Lua API Reference

clerk_list_users

List users from Clerk with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of users to return (default: 10, max: 500).
offsetintegernoNumber of users to skip for pagination.
email_addressstringnoFilter users by email address.
phone_numberstringnoFilter users by phone number.
querystringnoSearch query to filter users by name, email, or username.
order_bystringnoSort order: "+created_at" (ascending) or "-created_at" (descending).

Examples

-- List all users
local result = app.integrations.clerk.list_users({})

-- Search for a user by name or email
local result = app.integrations.clerk.list_users({
  query = "john"
})

-- Paginate through users
local result = app.integrations.clerk.list_users({
  limit = 50,
  offset = 100,
  order_by = "-created_at"
})

clerk_get_user

Retrieve a single Clerk user by their ID.

Parameters

NameTypeRequiredDescription
idstringyesThe Clerk user ID (e.g., "user_2abc123").

Examples

local result = app.integrations.clerk.get_user({
  id = "user_2abc123"
})

clerk_create_user

Create a new user in Clerk.

Parameters

NameTypeRequiredDescription
email_addressarrayyesArray of email addresses for the user. At least one is required.
first_namestringnoThe user’s first name.
last_namestringnoThe user’s last name.
passwordstringnoThe user’s password (minimum 8 characters).
usernamestringnoThe user’s username.

Examples

-- Create a user with email and name
local result = app.integrations.clerk.create_user({
  email_address = { "[email protected]" },
  first_name = "John",
  last_name = "Doe",
  password = "securepassword123"
})

-- Create a user with multiple emails
local result = app.integrations.clerk.create_user({
  email_address = { "[email protected]", "[email protected]" },
  first_name = "John",
  username = "johndoe"
})

clerk_update_user

Update an existing Clerk user’s profile.

Parameters

NameTypeRequiredDescription
idstringyesThe Clerk user ID to update.
first_namestringnoUpdated first name.
last_namestringnoUpdated last name.
usernamestringnoUpdated username.

Examples

-- Update a user's name
local result = app.integrations.clerk.update_user({
  id = "user_2abc123",
  first_name = "Jane",
  last_name = "Smith"
})

-- Update username only
local result = app.integrations.clerk.update_user({
  id = "user_2abc123",
  username = "janesmith"
})

clerk_delete_user

Delete a user from Clerk. This action is irreversible.

Parameters

NameTypeRequiredDescription
idstringyesThe Clerk user ID to delete.

Examples

local result = app.integrations.clerk.delete_user({
  id = "user_2abc123"
})

clerk_list_organizations

List organizations from Clerk with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of organizations to return (default: 10, max: 500).
offsetintegernoNumber of organizations to skip for pagination.
querystringnoSearch query to filter organizations by name.

Examples

-- List all organizations
local result = app.integrations.clerk.list_organizations({})

-- Search for an organization
local result = app.integrations.clerk.list_organizations({
  query = "Acme"
})

-- Paginate
local result = app.integrations.clerk.list_organizations({
  limit = 50,
  offset = 0
})

clerk_get_current_user

Health check — verify Clerk API connectivity by fetching the first user.

Parameters

None.

Examples

local result = app.integrations.clerk.get_current_user({})
if result.connected then
  print("Clerk API is reachable")
end

Multi-Account Usage

If you have multiple Clerk applications configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.clerk.function_name({})

-- Explicit default (portable across setups)
app.integrations.clerk.default.function_name({})

-- Named accounts
app.integrations.clerk.production.function_name({})
app.integrations.clerk.staging.function_name({})

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

Raw agent markdown 
# Clerk — Lua API Reference

## clerk_list_users

List users from Clerk with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of users to return (default: 10, max: 500). |
| `offset` | integer | no | Number of users to skip for pagination. |
| `email_address` | string | no | Filter users by email address. |
| `phone_number` | string | no | Filter users by phone number. |
| `query` | string | no | Search query to filter users by name, email, or username. |
| `order_by` | string | no | Sort order: `"+created_at"` (ascending) or `"-created_at"` (descending). |

### Examples

```lua
-- List all users
local result = app.integrations.clerk.list_users({})

-- Search for a user by name or email
local result = app.integrations.clerk.list_users({
  query = "john"
})

-- Paginate through users
local result = app.integrations.clerk.list_users({
  limit = 50,
  offset = 100,
  order_by = "-created_at"
})
```

---

## clerk_get_user

Retrieve a single Clerk user by their ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Clerk user ID (e.g., `"user_2abc123"`). |

### Examples

```lua
local result = app.integrations.clerk.get_user({
  id = "user_2abc123"
})
```

---

## clerk_create_user

Create a new user in Clerk.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email_address` | array | yes | Array of email addresses for the user. At least one is required. |
| `first_name` | string | no | The user's first name. |
| `last_name` | string | no | The user's last name. |
| `password` | string | no | The user's password (minimum 8 characters). |
| `username` | string | no | The user's username. |

### Examples

```lua
-- Create a user with email and name
local result = app.integrations.clerk.create_user({
  email_address = { "[email protected]" },
  first_name = "John",
  last_name = "Doe",
  password = "securepassword123"
})

-- Create a user with multiple emails
local result = app.integrations.clerk.create_user({
  email_address = { "[email protected]", "[email protected]" },
  first_name = "John",
  username = "johndoe"
})
```

---

## clerk_update_user

Update an existing Clerk user's profile.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Clerk user ID to update. |
| `first_name` | string | no | Updated first name. |
| `last_name` | string | no | Updated last name. |
| `username` | string | no | Updated username. |

### Examples

```lua
-- Update a user's name
local result = app.integrations.clerk.update_user({
  id = "user_2abc123",
  first_name = "Jane",
  last_name = "Smith"
})

-- Update username only
local result = app.integrations.clerk.update_user({
  id = "user_2abc123",
  username = "janesmith"
})
```

---

## clerk_delete_user

Delete a user from Clerk. This action is irreversible.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The Clerk user ID to delete. |

### Examples

```lua
local result = app.integrations.clerk.delete_user({
  id = "user_2abc123"
})
```

---

## clerk_list_organizations

List organizations from Clerk with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of organizations to return (default: 10, max: 500). |
| `offset` | integer | no | Number of organizations to skip for pagination. |
| `query` | string | no | Search query to filter organizations by name. |

### Examples

```lua
-- List all organizations
local result = app.integrations.clerk.list_organizations({})

-- Search for an organization
local result = app.integrations.clerk.list_organizations({
  query = "Acme"
})

-- Paginate
local result = app.integrations.clerk.list_organizations({
  limit = 50,
  offset = 0
})
```

---

## clerk_get_current_user

Health check — verify Clerk API connectivity by fetching the first user.

### Parameters

None.

### Examples

```lua
local result = app.integrations.clerk.get_current_user({})
if result.connected then
  print("Clerk API is reachable")
end
```

---

## Multi-Account Usage

If you have multiple Clerk applications configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.clerk.function_name({})

-- Explicit default (portable across setups)
app.integrations.clerk.default.function_name({})

-- Named accounts
app.integrations.clerk.production.function_name({})
app.integrations.clerk.staging.function_name({})
```

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

Metadata-Derived Lua Example

local result = app.integrations.clerk.clerk_list_users({
  limit = 1,
  offset = 1,
  email_address = "example_email_address",
  phone_number = "example_phone_number",
  query = "example_query",
  order_by = "example_order_by"
})
print(result)

Functions

clerk_list_users

List users from Clerk with optional filtering and pagination. Returns user IDs, emails, names, and profile details.

Operation
Read read
Full name
clerk.clerk_list_users
ParameterTypeRequiredDescription
limit integer no Maximum number of users to return (default: 10, max: 500).
offset integer no Number of users to skip for pagination.
email_address string no Filter users by email address.
phone_number string no Filter users by phone number.
query string no Search query to filter users by name, email, or username.
order_by string no Sort order for results. Use "+created_at" for ascending or "-created_at" for descending (default: "+created_at").

clerk_get_user

Retrieve a single Clerk user by their user ID. Returns full profile details including email, name, and metadata.

Operation
Read read
Full name
clerk.clerk_get_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID (e.g., "user_2abc123").

clerk_create_user

Create a new user in Clerk. Requires at least one email address. Optionally set name, password, and username.

Operation
Write write
Full name
clerk.clerk_create_user
ParameterTypeRequiredDescription
email_address array yes Array of email addresses for the user. At least one is required.
first_name string no The user's first name.
last_name string no The user's last name.
password string no The user's password. Minimum 8 characters.
username string no The user's username.

clerk_update_user

Update an existing Clerk user's profile. Provide the user ID and fields to update.

Operation
Write write
Full name
clerk.clerk_update_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID to update (e.g., "user_2abc123").
first_name string no Updated first name.
last_name string no Updated last name.
username string no Updated username.

clerk_delete_user

Delete a user from Clerk. This action is irreversible and will remove all associated data.

Operation
Write write
Full name
clerk.clerk_delete_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID to delete (e.g., "user_2abc123").

clerk_list_organizations

List organizations from Clerk with optional filtering and pagination. Returns organization IDs, names, and metadata.

Operation
Read read
Full name
clerk.clerk_list_organizations
ParameterTypeRequiredDescription
limit integer no Maximum number of organizations to return (default: 10, max: 500).
offset integer no Number of organizations to skip for pagination.
query string no Search query to filter organizations by name.

clerk_get_current_user

Health check — verify Clerk API connectivity by fetching the first user. Returns a single user or empty result to confirm the API is reachable.

Operation
Read read
Full name
clerk.clerk_get_current_user
ParameterTypeRequiredDescription
No parameters.