Skip to main content
API Referencev1

REST API Documentation

Complete reference for the Akmatori REST API. Most endpoints require authentication via JWT token or API key, while alert webhooks and API docs are public.

Authentication

All API requests must include authentication. You can use either a JWT token or an API key.

bash
# Using Bearer Token
curl -H "Authorization: Bearer <your-jwt-token>" \
  https://your-instance/api/incidents

# Using API Key
curl -H "X-API-Key: <your-api-key>" \
  https://your-instance/api/incidents
Generate API keys in Settings → API Keys. Public endpoints like /api/docs, /api/openapi.yaml, and alert webhooks do not require auth.

Base URL

text
https://your-akmatori-instance/api
Visit /api/docs on your Akmatori instance for an interactive Swagger UI where you can explore and test all endpoints directly.

Endpoints

Incidents

GET/incidents

List incidents with pagination and optional Unix timestamp filters (page, per_page, from, to)

GET/incidents/:uuid

Get a specific incident by UUID, including execution state and logs

POST/incidents

Create and start a new API-driven incident. Request body requires task and may include optional context.

Skills

GET/skills

List all available skills

POST/skills

Create a new skill

GET/skills/:name

Get skill details by name

PUT/skills/:name

Update skill configuration

DELETE/skills/:name

Delete a skill (user-created only)

GET/skills/:name/prompt

Get skill prompt content

PUT/skills/:name/prompt

Update skill prompt

GET/skills/:name/tools

List tools assigned to a skill

PUT/skills/:name/tools

Assign tool instances to a skill

GET/skills/:name/scripts

List skill scripts

DELETE/skills/:name/scripts

Clear all scripts for a skill

GET/skills/:name/scripts/:filename

Get a specific script by filename

PUT/skills/:name/scripts/:filename

Create or update a skill script

DELETE/skills/:name/scripts/:filename

Delete a specific script

POST/skills/sync

Sync skills from filesystem to database

Tools

GET/tool-types

List available tool types

GET/tools

List configured tool instances

POST/tools

Create a new tool instance

GET/tools/:id

Get tool instance details

PUT/tools/:id

Update tool configuration

DELETE/tools/:id

Delete a tool instance

GET/tools/:id/ssh-keys

List SSH keys for an SSH tool

POST/tools/:id/ssh-keys

Add an SSH key to a tool

PUT/tools/:id/ssh-keys/:keyId

Update an SSH key

DELETE/tools/:id/ssh-keys/:keyId

Delete an SSH key

Alert Sources

GET/alert-source-types

List supported alert source types

GET/alert-sources

List configured alert sources

POST/alert-sources

Create a new alert source

GET/alert-sources/:uuid

Get alert source details by UUID

PUT/alert-sources/:uuid

Update alert source configuration

DELETE/alert-sources/:uuid

Delete an alert source

Context Files

GET/context

List all context files

POST/context

Upload a new context file (multipart form)

GET/context/:id

Get context file metadata

GET/context/:id/download

Download context file content

DELETE/context/:id

Delete a context file

POST/context/validate

Validate context file references in text

Runbooks

GET/runbooks

List all runbooks for AI-guided incident investigation

POST/runbooks

Create a new runbook (title, content)

GET/runbooks/:id

Get runbook details by ID

PUT/runbooks/:id

Update runbook title and content

DELETE/runbooks/:id

Delete a runbook

HTTP Connectors

GET/http-connectors

List all HTTP connectors for external API integration

POST/http-connectors

Create a new HTTP connector with tool definitions

GET/http-connectors/:id

Get HTTP connector details by ID

PUT/http-connectors/:id

Update HTTP connector configuration

DELETE/http-connectors/:id

Delete an HTTP connector

MCP Servers

GET/mcp-servers

List all MCP server configurations for external tool proxying

POST/mcp-servers

Register a new MCP server (stdio or SSE transport)

GET/mcp-servers/:id

Get MCP server configuration by ID

PUT/mcp-servers/:id

Update MCP server configuration

DELETE/mcp-servers/:id

Delete an MCP server registration

Settings

GET/settings/general

Get general settings (base URL for links in notifications)

PUT/settings/general

Update general settings

GET/settings/slack

Get Slack integration settings

PUT/settings/slack

Update Slack integration settings

GET/settings/llm

Get LLM provider configuration (supports OpenAI, Anthropic, Google, OpenRouter, custom)

PUT/settings/llm

Update LLM provider configuration and set active provider

GET/settings/proxy

Get proxy configuration, including per-service support and enablement for LLM, Slack, Zabbix, VictoriaMetrics, Catchpoint, Grafana, PagerDuty, NetBox, and Kubernetes connectivity

PUT/settings/proxy

Update shared proxy configuration and per-service proxy toggles for supported integrations

GET/settings/retention

Get automated incident cleanup settings, including retention window and cleanup interval

PUT/settings/retention

Update retention policy configuration for automated incident data cleanup

Webhooks

POST/webhook/alert/:uuid

Receive alerts from monitoring systems (no auth required)

API Documentation

GET/docs

Interactive Swagger UI for exploring and testing API endpoints

GET/openapi.yaml

OpenAPI 3.0 specification in YAML format

Pagination

List endpoints support pagination via page and per_page query parameters. Default: page=1, per_page=50. Maximum per_page is 200.

bash
# Get page 2 with 25 items per page
curl -H "Authorization: Bearer <token>" \
  "https://your-instance/api/incidents?page=2&per_page=25"

# Filter by date range (Unix timestamps)
curl -H "Authorization: Bearer <token>" \
  "https://your-instance/api/incidents?from=1709251200&to=1709337600"

When using pagination, the response wraps data with metadata:

json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 147,
    "total_pages": 6
  }
}

Example Request

Create Incident
curl -X POST https://your-instance/api/incidents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Investigate sustained CPU saturation on web-server-01 and summarize likely root cause",
    "context": {
      "host": "web-server-01",
      "severity": "critical",
      "environment": "production"
    }
  }'

Error Responses

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
404Not Found - Resource doesn't exist
500Internal Error - Server error