KosmoKrator

analytics

Opsgenie Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.opsgenie.list_alerts({query = "example_query", limit = 1, offset = 1, sort = "example_sort", order = "example_order"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("opsgenie"))' --json
kosmo integrations:lua --eval 'print(docs.read("opsgenie.list_alerts"))' --json

Workflow file

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

workflow.lua 
local opsgenie = app.integrations.opsgenie
local result = opsgenie.list_alerts({query = "example_query", limit = 1, offset = 1, sort = "example_sort", order = "example_order"})

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

MCP-only Lua

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

Opsgenie — Lua API Reference

list_alerts

List Opsgenie alerts with optional filtering.

Parameters

NameTypeRequiredDescription
querystringnoSearch query (e.g., "status:open AND priority:P1")
limitintegernoMax results to return (default: 20, max: 100)
offsetintegernoPagination offset (default: 0)
sortstringnoSort field (e.g., "createdAt", "updatedAt")
orderstringnoSort order: "asc" or "desc" (default: "desc")

Example

local result = app.integrations.opsgenie.list_alerts({
  query = "status:open",
  limit = 10
})

for _, alert in ipairs(result.data or {}) do
  print(alert.id .. ": " .. alert.message .. " [" .. alert.priority .. "]")
end

get_alert

Get full details of a specific Opsgenie alert.

Parameters

NameTypeRequiredDescription
alert_idstringyesThe Opsgenie alert ID

Example

local result = app.integrations.opsgenie.get_alert({
  alert_id = "abc123-def456"
})

print("Message: " .. result.data.message)
print("Status: " .. result.data.status)
print("Priority: " .. result.data.priority)

create_alert

Create a new Opsgenie alert.

Parameters

NameTypeRequiredDescription
messagestringyesAlert message text
aliasstringnoClient-defined identifier (for deduplication)
descriptionstringnoDetailed description
prioritystringnoPriority: "P1", "P2", "P3", "P4", or "P5" (default: "P3")
teamsarraynoTeam names to route to (e.g., {"ops", "engineering"})
visibleToarraynoTeams/users visible to (no notifications)
actionsarraynoCustom actions (e.g., {"Restart", "ScaleUp"})
tagsarraynoTags (e.g., {"production", "critical"})
detailsobjectnoKey-value map of extra details
entitystringnoDomain of the alert
sourcestringnoSource (e.g., "monitoring")
userstringnoDisplay name of the request owner
notestringnoAdditional note

Example

local result = app.integrations.opsgenie.create_alert({
  message = "Production database CPU above 95%",
  priority = "P1",
  description = "CPU utilization has exceeded 95% for the last 10 minutes on db-primary-01.",
  teams = {"ops", "backend"},
  tags = {"production", "database", "critical"},
  actions = {"Restart Database", "Scale Up"},
  source = "monitoring"
})

print("Alert created: " .. (result.requestId or "ok"))

list_incidents

List Opsgenie incidents with optional filtering.

Parameters

NameTypeRequiredDescription
querystringnoSearch query (e.g., "status:open AND priority:P1")
limitintegernoMax results to return (default: 20, max: 100)
offsetintegernoPagination offset (default: 0)
sortstringnoSort field (e.g., "createdAt", "updatedAt")
orderstringnoSort order: "asc" or "desc" (default: "desc")

Example

local result = app.integrations.opsgenie.list_incidents({
  query = "status:open",
  limit = 10
})

for _, incident in ipairs(result.data or {}) do
  print(incident.id .. ": " .. incident.message .. " [" .. incident.status .. "]")
end

get_incident

Get full details of a specific Opsgenie incident.

Parameters

NameTypeRequiredDescription
incident_idstringyesThe Opsgenie incident ID

Example

local result = app.integrations.opsgenie.get_incident({
  incident_id = "inc-abc123"
})

print("Message: " .. result.data.message)
print("Status: " .. result.data.status)
print("Priority: " .. result.data.priority)

list_teams

List all Opsgenie teams.

Parameters

None.

Example

local result = app.integrations.opsgenie.list_teams({})

for _, team in ipairs(result.data or {}) do
  print(team.id .. ": " .. team.name)
end

get_current_user

Get the currently authenticated Opsgenie user.

Parameters

None.

Example

local result = app.integrations.opsgenie.get_current_user({})

print("User: " .. (result.data.username or "unknown"))
print("Name: " .. (result.data.fullName or "unknown"))
print("Email: " .. (result.data.emailAddress or "unknown"))

Multi-Account Usage

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

-- Default account (always works)
app.integrations.opsgenie.list_alerts({})

-- Explicit default (portable across setups)
app.integrations.opsgenie.default.list_alerts({})

-- Named accounts
app.integrations.opsgenie.production.list_alerts({})
app.integrations.opsgenie.staging.list_alerts({})

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

Common Patterns

Check for high-priority open alerts

local result = app.integrations.opsgenie.list_alerts({
  query = "status:open AND priority:P1",
  limit = 50
})

local critical = result.data or {}

if #critical > 0 then
  print(#critical .. " critical alerts found!")
  for _, alert in ipairs(critical) do
    print("  - " .. alert.message .. " (" .. alert.priority .. ")")
  end
else
  print("No critical alerts — all clear.")
end

Create an alert from an incident trigger

local incidents = app.integrations.opsgenie.list_incidents({
  query = "status:open",
  limit = 10
})

for _, incident in ipairs(incidents.data or {}) do
  if incident.priority == "P1" then
    app.integrations.opsgenie.create_alert({
      message = "ESCALATION: " .. incident.message,
      priority = "P1",
      teams = {"management"},
      tags = {"escalation", "auto"},
      note = "Auto-escalated from incident " .. incident.id
    })
  end
end
Raw agent markdown 
# Opsgenie — Lua API Reference

## list_alerts

List Opsgenie alerts with optional filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | no | Search query (e.g., `"status:open AND priority:P1"`) |
| `limit` | integer | no | Max results to return (default: 20, max: 100) |
| `offset` | integer | no | Pagination offset (default: 0) |
| `sort` | string | no | Sort field (e.g., `"createdAt"`, `"updatedAt"`) |
| `order` | string | no | Sort order: `"asc"` or `"desc"` (default: `"desc"`) |

### Example

```lua
local result = app.integrations.opsgenie.list_alerts({
  query = "status:open",
  limit = 10
})

for _, alert in ipairs(result.data or {}) do
  print(alert.id .. ": " .. alert.message .. " [" .. alert.priority .. "]")
end
```

---

## get_alert

Get full details of a specific Opsgenie alert.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `alert_id` | string | yes | The Opsgenie alert ID |

### Example

```lua
local result = app.integrations.opsgenie.get_alert({
  alert_id = "abc123-def456"
})

print("Message: " .. result.data.message)
print("Status: " .. result.data.status)
print("Priority: " .. result.data.priority)
```

---

## create_alert

Create a new Opsgenie alert.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `message` | string | yes | Alert message text |
| `alias` | string | no | Client-defined identifier (for deduplication) |
| `description` | string | no | Detailed description |
| `priority` | string | no | Priority: `"P1"`, `"P2"`, `"P3"`, `"P4"`, or `"P5"` (default: `"P3"`) |
| `teams` | array | no | Team names to route to (e.g., `{"ops", "engineering"}`) |
| `visibleTo` | array | no | Teams/users visible to (no notifications) |
| `actions` | array | no | Custom actions (e.g., `{"Restart", "ScaleUp"}`) |
| `tags` | array | no | Tags (e.g., `{"production", "critical"}`) |
| `details` | object | no | Key-value map of extra details |
| `entity` | string | no | Domain of the alert |
| `source` | string | no | Source (e.g., `"monitoring"`) |
| `user` | string | no | Display name of the request owner |
| `note` | string | no | Additional note |

### Example

```lua
local result = app.integrations.opsgenie.create_alert({
  message = "Production database CPU above 95%",
  priority = "P1",
  description = "CPU utilization has exceeded 95% for the last 10 minutes on db-primary-01.",
  teams = {"ops", "backend"},
  tags = {"production", "database", "critical"},
  actions = {"Restart Database", "Scale Up"},
  source = "monitoring"
})

print("Alert created: " .. (result.requestId or "ok"))
```

---

## list_incidents

List Opsgenie incidents with optional filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | no | Search query (e.g., `"status:open AND priority:P1"`) |
| `limit` | integer | no | Max results to return (default: 20, max: 100) |
| `offset` | integer | no | Pagination offset (default: 0) |
| `sort` | string | no | Sort field (e.g., `"createdAt"`, `"updatedAt"`) |
| `order` | string | no | Sort order: `"asc"` or `"desc"` (default: `"desc"`) |

### Example

```lua
local result = app.integrations.opsgenie.list_incidents({
  query = "status:open",
  limit = 10
})

for _, incident in ipairs(result.data or {}) do
  print(incident.id .. ": " .. incident.message .. " [" .. incident.status .. "]")
end
```

---

## get_incident

Get full details of a specific Opsgenie incident.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `incident_id` | string | yes | The Opsgenie incident ID |

### Example

```lua
local result = app.integrations.opsgenie.get_incident({
  incident_id = "inc-abc123"
})

print("Message: " .. result.data.message)
print("Status: " .. result.data.status)
print("Priority: " .. result.data.priority)
```

---

## list_teams

List all Opsgenie teams.

### Parameters

None.

### Example

```lua
local result = app.integrations.opsgenie.list_teams({})

for _, team in ipairs(result.data or {}) do
  print(team.id .. ": " .. team.name)
end
```

---

## get_current_user

Get the currently authenticated Opsgenie user.

### Parameters

None.

### Example

```lua
local result = app.integrations.opsgenie.get_current_user({})

print("User: " .. (result.data.username or "unknown"))
print("Name: " .. (result.data.fullName or "unknown"))
print("Email: " .. (result.data.emailAddress or "unknown"))
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.opsgenie.list_alerts({})

-- Explicit default (portable across setups)
app.integrations.opsgenie.default.list_alerts({})

-- Named accounts
app.integrations.opsgenie.production.list_alerts({})
app.integrations.opsgenie.staging.list_alerts({})
```

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

---

## Common Patterns

### Check for high-priority open alerts

```lua
local result = app.integrations.opsgenie.list_alerts({
  query = "status:open AND priority:P1",
  limit = 50
})

local critical = result.data or {}

if #critical > 0 then
  print(#critical .. " critical alerts found!")
  for _, alert in ipairs(critical) do
    print("  - " .. alert.message .. " (" .. alert.priority .. ")")
  end
else
  print("No critical alerts — all clear.")
end
```

### Create an alert from an incident trigger

```lua
local incidents = app.integrations.opsgenie.list_incidents({
  query = "status:open",
  limit = 10
})

for _, incident in ipairs(incidents.data or {}) do
  if incident.priority == "P1" then
    app.integrations.opsgenie.create_alert({
      message = "ESCALATION: " .. incident.message,
      priority = "P1",
      teams = {"management"},
      tags = {"escalation", "auto"},
      note = "Auto-escalated from incident " .. incident.id
    })
  end
end
```
Metadata-derived Lua example 
local result = app.integrations.opsgenie.list_alerts({query = "example_query", limit = 1, offset = 1, sort = "example_sort", order = "example_order"})
print(result)

Functions

list_alerts Read

List Opsgenie alerts. Optionally filter by query, status, or priority. Returns alert IDs, messages, statuses, and priorities.

Lua path
app.integrations.opsgenie.list_alerts
Full name
opsgenie.opsgenie_list_alerts
ParameterTypeRequiredDescription
query string no Search query to filter alerts (e.g., "status:open AND priority:P1").
limit integer no Maximum number of alerts to return (default: 20, max: 100).
offset integer no Offset for pagination (default: 0).
sort string no Sort field (e.g., "createdAt", "updatedAt").
order string no Sort order: "asc" or "desc" (default: "desc").
get_alert Read

Get full details of a specific Opsgenie alert by its ID. Returns message, description, priority, status, tags, and recipients.

Lua path
app.integrations.opsgenie.get_alert
Full name
opsgenie.opsgenie_get_alert
ParameterTypeRequiredDescription
alert_id string yes The Opsgenie alert ID.
create_alert Write

Create a new Opsgenie alert. Specify message, priority (P1–P5), and optional description, alias, tags, teams, or recipients.

Lua path
app.integrations.opsgenie.create_alert
Full name
opsgenie.opsgenie_create_alert
ParameterTypeRequiredDescription
message string yes Alert message text.
alias string no Client-defined identifier for the alert (used for deduplication).
description string no Detailed description of the alert.
priority string no Alert priority: "P1", "P2", "P3", "P4", or "P5". Defaults to "P3".
teams array no List of team names to route the alert to (e.g., ["ops", "engineering"]).
visibleTo array no List of teams/users the alert will be visible to without sending notifications.
actions array no Custom actions available on the alert (e.g., ["Restart", "ScaleUp"]).
tags array no List of tags for the alert (e.g., ["production", "critical"]).
details object no Key-value map of additional alert details.
entity string no Entity field used to specify the domain of the alert.
source string no Source field of the alert (e.g., "monitoring", "custom").
user string no Display name of the request owner.
note string no Additional note to add to the alert.
list_incidents Read

List Opsgenie incidents. Optionally filter by query, status, or priority. Returns incident IDs, messages, statuses, and priorities.

Lua path
app.integrations.opsgenie.list_incidents
Full name
opsgenie.opsgenie_list_incidents
ParameterTypeRequiredDescription
query string no Search query to filter incidents (e.g., "status:open AND priority:P1").
limit integer no Maximum number of incidents to return (default: 20, max: 100).
offset integer no Offset for pagination (default: 0).
sort string no Sort field (e.g., "createdAt", "updatedAt").
order string no Sort order: "asc" or "desc" (default: "desc").
get_incident Read

Get full details of a specific Opsgenie incident by its ID. Returns message, description, priority, status, impacted services, and responders.

Lua path
app.integrations.opsgenie.get_incident
Full name
opsgenie.opsgenie_get_incident
ParameterTypeRequiredDescription
incident_id string yes The Opsgenie incident ID.
list_teams Read

List all Opsgenie teams. Returns team IDs, names, and descriptions.

Lua path
app.integrations.opsgenie.list_teams
Full name
opsgenie.opsgenie_list_teams
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the currently authenticated Opsgenie user. Useful for verifying credentials and identifying the connected account.

Lua path
app.integrations.opsgenie.get_current_user
Full name
opsgenie.opsgenie_get_current_user
ParameterTypeRequiredDescription
No parameters.