productivity
OpenRouter Lua API for KosmoKrator Agents
Agent-facing Lua documentation and function reference for the OpenRouter KosmoKrator integration.Lua Namespace
Agents call this integration through app.integrations.openrouter.*.
Use lua_read_doc("integrations.openrouter") 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
OpenRouter workflow without starting an interactive agent session.
kosmo integrations:lua --eval 'dump(app.integrations.openrouter.list_models({}))' --jsonkosmo integrations:lua --eval 'print(docs.read("openrouter"))' --json
kosmo integrations:lua --eval 'print(docs.read("openrouter.list_models"))' --jsonWorkflow file
Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.
local openrouter = app.integrations.openrouter
local result = openrouter.list_models({})
dump(result)kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --jsonintegrations:lua exposes app.integrations.openrouter, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.openrouter.default.* or app.integrations.openrouter.work.* when you configured named credential accounts.
MCP-only Lua
If the script only needs configured MCP servers and does not need OpenRouter, use the narrower mcp:lua command.
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --jsonAgent-Facing Lua Docs
This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.
OpenRouter Lua API Reference
OpenRouter exposes model routing, chat completions, Responses-compatible calls, embeddings, reranking, media jobs, account activity, keys, workspaces, providers, guardrails, and generation records through one API key.
Namespace: app.integrations["openrouter"]
Common Patterns
Use the canonical chat endpoint when you want OpenAI-compatible chat completions:
local result = app.integrations["openrouter"].create_completion({
model = "openai/gpt-4o",
messages = {
{ role = "user", content = "Summarize this in one sentence." }
},
max_tokens = 120,
temperature = 0.2
})
print(result.choices[1].message.content)Use create_response, create_message, create_embedding, rerank, and create_video when an endpoint expects the official OpenRouter JSON payload. Pass that payload under payload:
local response = app.integrations["openrouter"].create_response({
payload = {
model = "openai/gpt-4o-mini",
input = "Write a release note."
}
})
local embedding = app.integrations["openrouter"].create_embedding({
payload = {
model = "openai/text-embedding-3-small",
input = "search text"
}
})Read tools that accept filters use a query object so agents can pass newly documented query parameters without waiting for a package release:
local generations = app.integrations["openrouter"].list_generations({
limit = 10
})
local activity = app.integrations["openrouter"].get_activity({
query = { limit = 25 }
})Tool Groups
Model and Provider Discovery
list_models({})count_models({ query = {...} })list_user_models({ query = {...} })list_model_endpoints({ author = "openai", slug = "gpt-4o-mini" })list_providers({})list_embedding_models({})list_video_models({})
Generation and Model Calls
create_completion({ model = "...", messages = {...}, max_tokens = 100, temperature = 0.2 })create_response({ payload = {...} })create_message({ payload = {...} })create_embedding({ payload = {...} })rerank({ payload = {...} })create_video({ payload = {...} })get_video({ job_id = "job_123" })
Generations, Usage, and Account State
list_generations({ limit = 10, offset = 0 })get_generation({ id = "gen_123" })get_generation_content({ id = "gen_123" })get_usage({ period = "month" })get_credits({})get_activity({ query = {...} })get_current_user({})
API Keys and Workspaces
list_api_keys({})get_api_key({ hash = "key_hash" })create_api_key({ payload = {...} })update_api_key({ hash = "key_hash", payload = {...} })delete_api_key({ hash = "key_hash" })list_organization_members({ query = {...} })list_workspaces({ query = {...} })get_workspace({ id = "workspace_123" })create_workspace({ payload = {...} })update_workspace({ id = "workspace_123", payload = {...} })delete_workspace({ id = "workspace_123" })list_guardrails({ query = {...} })
Raw OpenRouter Paths
For newly released endpoints, use guarded relative-path tools:
local zdr = app.integrations["openrouter"].api_get({
path = "/endpoints/zdr",
query = {}
})The raw tools only accept relative OpenRouter API paths. Absolute URLs and parent-directory traversal are rejected.
api_get({ path = "/path", query = {...} })api_post({ path = "/path", payload = {...} })api_patch({ path = "/path", payload = {...} })api_delete({ path = "/path", query = {...} })
Return Shapes
Tool responses are the decoded OpenRouter JSON response. This package does not flatten upstream fields for model calls, account records, keys, workspaces, or generation records because OpenRouter’s API returns endpoint-specific response shapes that agents often need intact.
Multi-Account Usage
app.integrations["openrouter"].list_models({})
app.integrations["openrouter"].default.list_models({})
app.integrations["openrouter"].work.list_models({})All accounts expose the same tools. Only credentials and optional base URL differ.
Raw agent markdown
# OpenRouter Lua API Reference
OpenRouter exposes model routing, chat completions, Responses-compatible calls, embeddings, reranking, media jobs, account activity, keys, workspaces, providers, guardrails, and generation records through one API key.
Namespace: `app.integrations["openrouter"]`
## Common Patterns
Use the canonical chat endpoint when you want OpenAI-compatible chat completions:
```lua
local result = app.integrations["openrouter"].create_completion({
model = "openai/gpt-4o",
messages = {
{ role = "user", content = "Summarize this in one sentence." }
},
max_tokens = 120,
temperature = 0.2
})
print(result.choices[1].message.content)
```
Use `create_response`, `create_message`, `create_embedding`, `rerank`, and `create_video` when an endpoint expects the official OpenRouter JSON payload. Pass that payload under `payload`:
```lua
local response = app.integrations["openrouter"].create_response({
payload = {
model = "openai/gpt-4o-mini",
input = "Write a release note."
}
})
local embedding = app.integrations["openrouter"].create_embedding({
payload = {
model = "openai/text-embedding-3-small",
input = "search text"
}
})
```
Read tools that accept filters use a `query` object so agents can pass newly documented query parameters without waiting for a package release:
```lua
local generations = app.integrations["openrouter"].list_generations({
limit = 10
})
local activity = app.integrations["openrouter"].get_activity({
query = { limit = 25 }
})
```
## Tool Groups
### Model and Provider Discovery
- `list_models({})`
- `count_models({ query = {...} })`
- `list_user_models({ query = {...} })`
- `list_model_endpoints({ author = "openai", slug = "gpt-4o-mini" })`
- `list_providers({})`
- `list_embedding_models({})`
- `list_video_models({})`
### Generation and Model Calls
- `create_completion({ model = "...", messages = {...}, max_tokens = 100, temperature = 0.2 })`
- `create_response({ payload = {...} })`
- `create_message({ payload = {...} })`
- `create_embedding({ payload = {...} })`
- `rerank({ payload = {...} })`
- `create_video({ payload = {...} })`
- `get_video({ job_id = "job_123" })`
### Generations, Usage, and Account State
- `list_generations({ limit = 10, offset = 0 })`
- `get_generation({ id = "gen_123" })`
- `get_generation_content({ id = "gen_123" })`
- `get_usage({ period = "month" })`
- `get_credits({})`
- `get_activity({ query = {...} })`
- `get_current_user({})`
### API Keys and Workspaces
- `list_api_keys({})`
- `get_api_key({ hash = "key_hash" })`
- `create_api_key({ payload = {...} })`
- `update_api_key({ hash = "key_hash", payload = {...} })`
- `delete_api_key({ hash = "key_hash" })`
- `list_organization_members({ query = {...} })`
- `list_workspaces({ query = {...} })`
- `get_workspace({ id = "workspace_123" })`
- `create_workspace({ payload = {...} })`
- `update_workspace({ id = "workspace_123", payload = {...} })`
- `delete_workspace({ id = "workspace_123" })`
- `list_guardrails({ query = {...} })`
## Raw OpenRouter Paths
For newly released endpoints, use guarded relative-path tools:
```lua
local zdr = app.integrations["openrouter"].api_get({
path = "/endpoints/zdr",
query = {}
})
```
The raw tools only accept relative OpenRouter API paths. Absolute URLs and parent-directory traversal are rejected.
- `api_get({ path = "/path", query = {...} })`
- `api_post({ path = "/path", payload = {...} })`
- `api_patch({ path = "/path", payload = {...} })`
- `api_delete({ path = "/path", query = {...} })`
## Return Shapes
Tool responses are the decoded OpenRouter JSON response. This package does not flatten upstream fields for model calls, account records, keys, workspaces, or generation records because OpenRouter's API returns endpoint-specific response shapes that agents often need intact.
## Multi-Account Usage
```lua
app.integrations["openrouter"].list_models({})
app.integrations["openrouter"].default.list_models({})
app.integrations["openrouter"].work.list_models({})
```
All accounts expose the same tools. Only credentials and optional base URL differ.local result = app.integrations.openrouter.list_models({})
print(result)Functions
list_models Read
List available AI models on OpenRouter. Returns model identifiers, names, pricing, context lengths, and capabilities.
- Lua path
app.integrations.openrouter.list_models- Full name
openrouter.openrouter_list_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_completion Write
Create a chat completion using any model available on OpenRouter. Supports multi-turn conversations, system prompts, temperature control, and configurable output length.
- Lua path
app.integrations.openrouter.create_completion- Full name
openrouter.openrouter_create_completion
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | yes | The model to use (e.g., "openai/gpt-4o", "anthropic/claude-3.5-sonnet", "meta-llama/llama-3-70b-instruct"). |
messages | array | yes | Array of message objects with "role" ("system", "user", or "assistant") and "content" (string). |
max_tokens | integer | no | Maximum number of tokens to generate in the response. |
temperature | number | no | Controls randomness in generation (0.0-2.0). Lower values are more deterministic. |
top_p | number | no | Nucleus sampling parameter (0.0-1.0). Limits cumulative probability of tokens considered. |
stop | array | no | Array of strings that will cause the model to stop generating if encountered. |
stream | boolean | no | Whether to stream the response incrementally (default: false). |
create_response Write
Create a response through the Responses-compatible endpoint.
- Lua path
app.integrations.openrouter.create_response- Full name
openrouter.openrouter_create_response
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_message Write
Create a message through the messages endpoint.
- Lua path
app.integrations.openrouter.create_message- Full name
openrouter.openrouter_create_message
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_embedding Write
Create embeddings using an OpenRouter embedding model.
- Lua path
app.integrations.openrouter.create_embedding- Full name
openrouter.openrouter_create_embedding
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_embedding_models Read
List models that support embeddings.
- Lua path
app.integrations.openrouter.list_embedding_models- Full name
openrouter.openrouter_list_embedding_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
rerank_documents Write
Rerank documents for a query using OpenRouter reranking models.
- Lua path
app.integrations.openrouter.rerank_documents- Full name
openrouter.openrouter_rerank
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_generations Read
List generation records from OpenRouter. Returns generation IDs, models used, token counts, and costs.
- Lua path
app.integrations.openrouter.list_generations- Full name
openrouter.openrouter_list_generations
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Maximum number of generations to return per page. |
offset | integer | no | Number of generations to skip for pagination. |
order | string | no | Sort order: "asc" or "desc" (default: "desc"). |
get_generation Read
Get details for a specific OpenRouter generation, including token usage, costs, and latency.
- Lua path
app.integrations.openrouter.get_generation- Full name
openrouter.openrouter_get_generation
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The generation identifier. |
get_generation_content Read
Get stored prompt and completion content for a generation.
- Lua path
app.integrations.openrouter.get_generation_content- Full name
openrouter.openrouter_get_generation_content
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
count_models Read
Count available models with optional OpenRouter filters.
- Lua path
app.integrations.openrouter.count_models- Full name
openrouter.openrouter_count_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_user_models Read
List models filtered by the account preferences and guardrails.
- Lua path
app.integrations.openrouter.list_user_models- Full name
openrouter.openrouter_list_user_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_model_endpoints Read
List provider endpoints for a specific OpenRouter model.
- Lua path
app.integrations.openrouter.list_model_endpoints- Full name
openrouter.openrouter_list_model_endpoints
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_providers Read
List OpenRouter providers and availability metadata.
- Lua path
app.integrations.openrouter.list_providers- Full name
openrouter.openrouter_list_providers
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_credits Read
Get the account credit balance.
- Lua path
app.integrations.openrouter.get_credits- Full name
openrouter.openrouter_get_credits
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_activity Read
Get account activity with optional filters.
- Lua path
app.integrations.openrouter.get_activity- Full name
openrouter.openrouter_get_activity
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_api_keys Read
List API keys for the OpenRouter account. Returns key names, creation dates, and usage limits.
- Lua path
app.integrations.openrouter.list_api_keys- Full name
openrouter.openrouter_list_api_keys
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_api_key Read
Get one API key by hash.
- Lua path
app.integrations.openrouter.get_api_key- Full name
openrouter.openrouter_get_api_key
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_api_key Write
Create an API key with OpenRouter key limits and metadata.
- Lua path
app.integrations.openrouter.create_api_key- Full name
openrouter.openrouter_create_api_key
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
update_api_key Write
Update an OpenRouter API key by hash.
- Lua path
app.integrations.openrouter.update_api_key- Full name
openrouter.openrouter_update_api_key
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
delete_api_key Write
Delete an OpenRouter API key by hash.
- Lua path
app.integrations.openrouter.delete_api_key- Full name
openrouter.openrouter_delete_api_key
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_usage Read
Get usage statistics for the OpenRouter account, including token counts and costs.
- Lua path
app.integrations.openrouter.get_usage- Full name
openrouter.openrouter_get_usage
| Parameter | Type | Required | Description |
|---|---|---|---|
period | string | no | Time period for usage data (e.g., "day", "week", "month"). |
get_current_user Read
Get the authenticated user's profile and account information.
- Lua path
app.integrations.openrouter.get_current_user- Full name
openrouter.openrouter_get_current_user
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_organization_members Read
List OpenRouter organization members.
- Lua path
app.integrations.openrouter.list_organization_members- Full name
openrouter.openrouter_list_organization_members
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_workspaces Read
List OpenRouter workspaces.
- Lua path
app.integrations.openrouter.list_workspaces- Full name
openrouter.openrouter_list_workspaces
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_workspace Read
Get one OpenRouter workspace.
- Lua path
app.integrations.openrouter.get_workspace- Full name
openrouter.openrouter_get_workspace
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_workspace Write
Create an OpenRouter workspace.
- Lua path
app.integrations.openrouter.create_workspace- Full name
openrouter.openrouter_create_workspace
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
update_workspace Write
Update an OpenRouter workspace.
- Lua path
app.integrations.openrouter.update_workspace- Full name
openrouter.openrouter_update_workspace
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
delete_workspace Write
Delete an OpenRouter workspace.
- Lua path
app.integrations.openrouter.delete_workspace- Full name
openrouter.openrouter_delete_workspace
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_guardrails Read
List guardrails configured for the account.
- Lua path
app.integrations.openrouter.list_guardrails- Full name
openrouter.openrouter_list_guardrails
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_video_models Read
List models that support video generation.
- Lua path
app.integrations.openrouter.list_video_models- Full name
openrouter.openrouter_list_video_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_video Write
Submit a video generation request.
- Lua path
app.integrations.openrouter.create_video- Full name
openrouter.openrouter_create_video
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_video Read
Poll video generation job status.
- Lua path
app.integrations.openrouter.get_video- Full name
openrouter.openrouter_get_video
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
api_get Read
Call a safe relative OpenRouter GET path for newly released endpoints.
- Lua path
app.integrations.openrouter.api_get- Full name
openrouter.openrouter_api_get
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
api_post Write
Call a safe relative OpenRouter POST path for newly released endpoints.
- Lua path
app.integrations.openrouter.api_post- Full name
openrouter.openrouter_api_post
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
api_patch Write
Call a safe relative OpenRouter PATCH path for newly released endpoints.
- Lua path
app.integrations.openrouter.api_patch- Full name
openrouter.openrouter_api_patch
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
api_delete Write
Call a safe relative OpenRouter DELETE path for newly released endpoints.
- Lua path
app.integrations.openrouter.api_delete- Full name
openrouter.openrouter_api_delete
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||