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

Endpoints

Incidents

GET/incidents

List all incidents with optional filters

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

Settings

GET/settings/slack

Get Slack integration settings

PUT/settings/slack

Update Slack integration settings

GET/settings/openai

Get OpenAI/LLM configuration

PUT/settings/openai

Update OpenAI/LLM configuration

POST/settings/openai/device-auth/start

Start ChatGPT device authentication flow

GET/settings/openai/device-auth/status

Check device authentication status

POST/settings/openai/device-auth/cancel

Cancel ongoing device authentication

POST/settings/openai/chatgpt/disconnect

Disconnect ChatGPT subscription

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)

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