API Referencev1

REST API Documentation

Complete reference for the Akmatori REST API. All endpoints require authentication via JWT token or API key.

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. Tokens expire after 24 hours.

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 optional filters and pagination (page, per_page, from, to)

GET/incidents/:id

Get a specific incident by ID

POST/incidents

Create and run a new incident investigation

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

Incident Alerts

GET/incidents/:uuid/alerts

List alerts attached to an incident

POST/incidents/:uuid/alerts

Attach an alert to an incident

DELETE/incidents/:uuid/alerts/:alertId

Detach an alert from an incident

POST/incidents/:uuid/merge

Merge another incident into this one

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

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

PUT/settings/proxy

Update proxy configuration

GET/settings/aggregation

Get alert aggregation settings

PUT/settings/aggregation

Update alert aggregation settings

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 '{
    "title": "High CPU on web-server-01",
    "description": "CPU usage above 90% for 5 minutes",
    "skill": "investigate-high-cpu",
    "context": {
      "host": "web-server-01",
      "severity": "critical"
    }
  }'

Error Responses

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing token

404Not Found - Resource doesn't exist

500Internal Error - Server error