Skip to main content

REST API reference

Reference for the Akmatori REST API. Most endpoints require a JWT. Login, first-run setup, the health check, alert webhooks, and the API docs are public.

Authentication

Most API requests require a JWT. Get one from POST /auth/login and send it in the Authorization: Bearer <token> header. For browser downloads that cannot set headers, you can also pass it as the token query parameter. A token is valid for 24 hours by default (JWT_EXPIRY_HOURS). Akmatori does not accept API keys.

bash
# Get a token (valid for 24 hours by default)
curl -X POST https://your-instance/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<your-password>"}'
# => {"token": "<jwt>", "username": "admin", "expires_in": 86400}

# Send the token as a Bearer token
curl -H "Authorization: Bearer <jwt>" \
  https://your-instance/api/incidents
Public endpoints: /auth/login, /auth/setup-status, /auth/setup, /health, /api/docs, /api/openapi.yaml, alert webhooks under /webhook/alert/:uuid, and the MCP OAuth redirect /api/mcp-servers/oauth/callback. Until the first-run setup is complete, every other endpoint returns 503 with code setup_required.

Base URL

text
https://your-akmatori-instance/api
Open /api/docs on your Akmatori instance for an interactive Swagger UI. It shows the endpoints in the OpenAPI document, which does not yet cover every endpoint on this page.

Endpoint paths on this page are relative to /api, except the /auth/*, /health and /webhook/* paths, which are at the root of the host. The machine-readable contract is published at akmatori.com/api/openapi.yaml (OpenAPI 3.1, also served at /openapi.yaml). Each instance serves its own copy at /api/openapi.yaml.

Endpoints

Incidents

GET/incidents

List incidents, newest first, with pagination (page, per_page) and optional filters: from and to (Unix seconds, on creation time) and status (comma-separated).

GET/incidents/:uuid

Get an incident by UUID, with its agent runs, latest response, full log, token count and execution time.

GET/incidents/:uuid/alerts

List the normalized alerts linked to an incident, oldest first, with their firing or resolved state.

GET/incidents/:uuid/response

Get only the latest agent response of an incident (uuid, title, status, response), without the log.

POST/incidents

Submit a task (task, required). Akmatori classifies the text first. A report of a problem becomes an alert that opens a new incident (status: "pending") or joins an open one ("linked"). A change or info note is stored on the Events page only ("recorded"). Any other text starts an agent request ("running"); read it with GET /requests/:uuid. Returns 201 with uuid, status, message, event_uuid and event_kind. The optional context object is accepted but not used.

POST/incidents/:uuid/close

Close an incident. If it still has firing alerts or a pending or running agent, the call returns 409 with requires_confirmation, firing_alert_count and in_progress; send {"confirm": true} to close it anyway and resolve its firing alerts. An incident that is already closed returns 409.

POST/incidents/:uuid/feedback

Send free-text operator feedback on an incident ({"text": "..."}). Akmatori stores it as a global feedback memory linked to the incident and returns it with 201.

POST/incidents/sweep-stale

Run the stale-incident auto-close sweep now. With ?dry_run=true it only reports the incidents it would close, even when auto-close is turned off.

GET/requests/:uuid

Get an agent request that is not an incident (an API or Slack request, a cron run, a proposal chat), with its runs, latest response and log.

GET/requests/:uuid/response

Get only the latest response of a request, without the log.

Alert lifecycle

POST/alerts/:uuid/unlink

Unlink an alert from its incident and start a new investigation for it. Returns 404 for an unknown alert and 409 when a concurrent request moved it.

POST/alerts/:uuid/move

Move an alert to the incident in target_incident_uuid. An empty or missing target works like unlink. A target that does not exist or is the current incident returns 400.

POST/alerts/:uuid/resolve

Mark a firing alert as resolved without waiting for a resolved webhook from its source. An alert that is already resolved returns 409.

Events

GET/events

List every inbound event (alert, change, info or request), newest first, with pagination. Filters: from and to (Unix seconds), kind, source (webhook, slack_listener, slack_mention, manual, cron, proposal) and search (UUID prefix, or text in the title or host).

GET/events/raw

Get the raw payload and original message of one event: ?uuid=<event_uuid> (required).

Skills

GET/skills

List all skills.

POST/skills

Create a skill with name (required, up to 64 characters) and optional description, category and prompt.

GET/skills/:name

Get a skill and its prompt by name.

PUT/skills/:name

Update description, category, enabled or prompt. Other fields are ignored. The generated connected-tools skill returns 403.

DELETE/skills/:name

Delete a skill. System skills return 403.

GET/skills/:name/prompt

Get the prompt of a skill.

PUT/skills/:name/prompt

Replace the prompt of a skill ({"prompt": "..."}).

GET/skills/:name/tools

Retired: GET and PUT return 410 Gone. Tools are not assigned to skills; every enabled connector is available to every skill (see the generated connected-tools skill).

GET/skills/:name/scripts

List the scripts of a skill.

DELETE/skills/:name/scripts

Delete all scripts of a skill.

GET/skills/:name/scripts/:filename

Get one script by file name.

PUT/skills/:name/scripts/:filename

Create or replace a script.

DELETE/skills/:name/scripts/:filename

Delete one script.

POST/skills/sync

Load skills from the file system into the database.

Connectors

GET/connectors

List connectors (the grouping of tools, alert webhooks, messaging integrations and MCP servers shown on the Connectors page) with capabilities and a coarse status: ok, connected, disabled, needs_setup, error or unknown. No credentials are returned.

GET/connectors/catalog

List every kind of connector that can be added, with its capabilities and the tool types, alert source types or messaging provider it accepts.

GET/connectors/lookup

Find the connector of a part: ?kind=tool_instance|alert_source|integration|mcp_server&id=N returns connector_uuid.

GET/connectors/:uuid

Get a connector with its parts: tool instances, alert sources (with last alert time), integrations (with channel counts) and the MCP server.

PATCH/connectors/:uuid

Rename a connector ({"name": "..."}). PUT works too.

DELETE/connectors/:uuid

Delete a connector and every part it groups: its tool instances, its alert sources (their webhook URLs stop working), its messaging integration with the channels, and its MCP server.

POST/connectors/:uuid/parts

Move a part into this connector with {"kind", "id"}. The part must match the connector type; a connector holds at most one MCP server. Webhook URLs and tool names do not change.

DELETE/connectors/:uuid/parts/:kind/:id

Move a part out into a new connector of its own. Returns the new connector_uuid.

Tools

GET/tool-types

List the tool types.

GET/tools

List the tool instances. Secret settings are masked and SSH private keys are left out.

POST/tools

Create a tool instance with tool_type_id and name (required), and optional logical_name (derived from the name when empty) and settings. Optional connector_uuid adds it to an existing connector; without it, Akmatori creates a new connector.

GET/tools/:id

Get a tool instance. Secret settings are masked.

PUT/tools/:id

Update name, logical_name, settings or enabled. Omitted fields keep their values. settings replaces the stored object, but SSH keys are kept and a secret sent as ******** keeps its stored value. The tool instance of an MCP server returns 409.

DELETE/tools/:id

Delete a tool instance. The tool instance that belongs to an MCP server returns 409; change it through /mcp-servers.

GET/tools/:id/ssh-keys

List the SSH keys of an SSH tool (without the private keys).

POST/tools/:id/ssh-keys

Add an SSH key with name and private_key (required) and optional is_default.

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

Change the name or is_default of an SSH key.

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

Delete an SSH key.

Alert sources

GET/alert-source-types

List the alert source types you can create. Deprecated types are not listed.

GET/alert-sources

List the alert sources.

POST/alert-sources

Create a webhook alert source with source_type_name and name (required), and optional description, webhook_secret, field_mappings, settings and notification_channel_uuid (a channel that can post). Optional connector_uuid adds it to an existing connector. Deprecated source types such as slack_channel return 400; set up Slack listeners through channels instead. A duplicate name returns 409.

GET/alert-sources/:uuid

Get an alert source by UUID.

PUT/alert-sources/:uuid

Update name, description, webhook_secret, field_mappings, settings, enabled or notification_channel_uuid. Omitted fields keep their values; an empty or null notification_channel_uuid clears the routing override.

DELETE/alert-sources/:uuid

Delete an alert source. Its webhook URL stops working.

Messaging integrations

GET/integrations

List messaging provider integrations (slack, telegram, discord), with credentials masked in responses.

POST/integrations

Create a provider integration with provider and name (required), a provider-specific credentials object (Slack: bot token, signing secret and app token; Telegram and Discord: bot_token, required), and optional enabled and connector_uuid.

GET/integrations/:uuid

Get an integration by UUID. Secret credentials are masked.

PUT/integrations/:uuid

Update name, credentials or enabled. A blank or omitted secret keeps the stored value. You cannot change the provider.

DELETE/integrations/:uuid

Delete a messaging integration and its channels.

POST/integrations/:uuid/test

Check the stored credentials with the provider (Slack auth.test, Telegram getMe, Discord /users/@me). Returns {"ok", "account", "error"}.

Channels

GET/channels

List channels, with optional filters integration_uuid, can_post and can_listen.

POST/channels

Create a channel with integration_uuid and the provider's external_id (both required), plus optional display_name, can_post, can_listen, is_default_post, extraction_prompt, process_bot_messages, process_human_messages and enabled. Telegram and Discord channels can only post: can_listen: true returns 400.

GET/channels/:uuid

Get a channel by UUID, with its integration (credentials masked).

PUT/channels/:uuid

Update any of the channel fields above except integration_uuid. Omitted fields keep their values.

DELETE/channels/:uuid

Delete a channel. Akmatori reloads the Slack listener routing.

Cron jobs

GET/cron-jobs

List scheduled agent jobs, with the target channel, next run time, system flag, last-run status, tools_enabled and builtin_tools.

POST/cron-jobs

Create an agent cron job with name, a five-field cron schedule and prompt, and optional channel_uuid (without it, the default channel is used), enabled, post_results, tools_enabled (all enabled connector tools or none; default on) and builtin_tools (any of events, incidents, proposals, runbooks, memory; default events, runbooks, memory). tool_instance_ids is refused with 400.

GET/cron-jobs/:uuid

Get a scheduled job, including last-run status, next run time, delivery target, system flag, tools_enabled and builtin_tools.

PUT/cron-jobs/:uuid

Update name, schedule, prompt, channel_uuid (an empty string clears it), enabled, post_results, tools_enabled or builtin_tools. Omitted fields keep their stored values.

POST/cron-jobs/:uuid/run

Start a job immediately in the background and return 202 Accepted.

DELETE/cron-jobs/:uuid

Delete a scheduled job that an operator created. System jobs return 409 Conflict; disable them with PUT instead.

Context files

GET/context

List all context files.

POST/context

Upload a context file as a multipart form with file and filename (required) and optional description. The maximum file size is 10 MB; a larger file returns 413.

GET/context/:id

Get the metadata of a context file.

GET/context/:id/download

Download the content of a context file.

DELETE/context/:id

Delete a context file.

POST/context/:id/summarize

Run the summary of a context file again, for example after a failure. Returns 202 with the file.

POST/context/validate

Check the context file references in a text ({"text": "..."}). Returns valid, references, found and missing.

Runbooks

GET/runbooks

List all runbooks.

POST/runbooks

Create a runbook (title, content). The agent can find it at once with the runbooks.search tool.

GET/runbooks/:id

Get a runbook by ID.

PUT/runbooks/:id

Update the title and content of a runbook.

DELETE/runbooks/:id

Delete a runbook.

Cross-incident memory

GET/memories

List cross-incident memories, with optional filters: scope, type, evidence grade, incident_uuid (memories that came from an incident) and used_in_incident (memories an incident's runs used).

POST/memories

Create a memory with scope, name (both lowercase slugs), type (fact or feedback) and description, plus optional body, incident_uuid, created_by (operator or agent), evidence (confirmed, observed or unverified), claim (causal or factual) and evidence_note. Set created_by to operator to protect the memory: agents cannot change operator memories.

GET/memories/scopes

List the scopes that have at least one memory.

GET/memories/:id

Get a single memory by ID, with its evidence grade, usage counts, and resolved [[...]] references.

PUT/memories/:id

Update a memory. Omitted fields keep their stored values; send "body": "" to clear the body.

DELETE/memories/:id

Delete a memory. Returns 204.

POST/memories/from-text

Create an operator memory from free text (text, required; optional scope, default global). A one-shot LLM call drafts it, with a plain fallback when no LLM is available. It never overwrites another memory: a taken name gets a -2, -3 suffix.

GET/memories/export

Download all memories as a zip of <scope>/<name>.md files.

POST/incidents/:uuid/extract-memory

Run the post-incident memory pass again for a closed incident. Returns 202, or 409 when the incident is not closed or a pass is pending or running.

POST/incidents/extract-memory-backfill

Queue the memory pass for incidents closed in the last days days (default 30, max 365) that never had one. Returns 202 with queued and since.

Self-improvement proposals

GET/proposals

List improvement proposals, with pagination and optional status and kind filters.

GET/proposals/count

Get the number of pending proposals ({"pending": n}).

GET/proposals/:uuid

Get one proposal, with its reasoning, the current content of the target and the proposed content.

POST/proposals/:uuid/approve

Approve a proposal. Akmatori applies the change at once. Returns 409 when the proposal cannot be approved or its target changed (the proposal is then superseded), and 422 when the change fails to apply.

POST/proposals/:uuid/reject

Reject a proposal.

GET/proposals/:uuid/chat

Get the review chat of a proposal: messages, chat_incident_uuid and chat_status (poll while it is running).

POST/proposals/:uuid/chat

Send an operator message ({"message": "..."}) to refine a pending proposal. An agent writes the reply. Returns 202; read the reply with GET. Returns 409 while the previous reply is still running.

HTTP connectors

GET/http-connectors

List the HTTP connectors (tool types that call an external HTTP API).

POST/http-connectors

Create an HTTP connector with tool_type_name and base_url_field (required), and optional description, auth_config and tools (your HTTP tool definitions). Add a tool instance with POST /tools to set the base URL and credentials.

GET/http-connectors/:id

Get an HTTP connector by ID.

PUT/http-connectors/:id

Update tool_type_name, description, base_url_field, auth_config, tools or enabled. Omitted fields keep their values.

DELETE/http-connectors/:id

Delete an HTTP connector.

MCP servers (custom connectors)

GET/mcp-servers

List remote MCP servers. Secrets in auth_config are replaced by ********; auth tells the auth type and whether a secret or OAuth sign-in is stored.

POST/mcp-servers

Add a remote MCP server with name and url (Streamable HTTP). Optional: namespace_prefix (default ext.<name>), auth_config (bearer, header or oauth), disabled_tools, connector_uuid. Local stdio servers (command, args, env_vars) are rejected. Akmatori also creates a managed tool instance for the server; its tools are then available to every skill.

GET/mcp-servers/:id

Get an MCP server (secrets masked).

PUT/mcp-servers/:id

Update an MCP server. auth_config: absent keeps it, null removes it, an object replaces it; a missing, empty or ******** secret keeps the stored one when the type does not change.

DELETE/mcp-servers/:id

Delete an MCP server with its managed tool instance and tool type.

POST/mcp-servers/test

Test unsaved settings (url, optional auth_config) through the gateway, with the same network policy as real calls. Returns the server info and tools; a connection failure returns 502. A 401 from the server sets auth_required.

POST/mcp-servers/:id/test

Test a stored server. Optional url and auth_config override the stored values one by one.

GET/mcp-servers/status

Get the gateway connection status of every MCP server: connected, tool count, tool names and last error.

POST/mcp-servers/:id/oauth/start

Start OAuth sign-in. Returns authorize_url to open in the browser. The redirect URL is <external URL>/api/mcp-servers/oauth/callback (set the external URL in Settings → General).

POST/mcp-servers/:id/oauth/disconnect

Forget the OAuth tokens of a server (the client registration is kept).

GET/mcp-servers/oauth/callback

Public OAuth redirect target. Exchanges the code and returns to the connector page with ?oauth=connected or ?oauth_error=….

Settings

GET/settings/general

Get the general settings: the base URL for links in notifications, alert correlation, event classification, incident merge and auto-close, and memory generation.

PUT/settings/general

Update the general settings: base_url, alert_correlation_enabled, alert_monitor_window_minutes, alert_correlation_prompt, event_classification_enabled, event_classification_prompt, incident_merge_enabled, incident_auto_close_enabled, incident_auto_close_minutes and memory_generation_enabled. Omitted fields keep their values; an empty prompt restores the default.

GET/settings/slack

Removed. Returns 410 Gone; use /integrations and /channels instead.

PUT/settings/slack

Removed. Returns 410 Gone; set up Slack through messaging integrations and channels.

GET/settings/llm

List all LLM configurations (configs, API keys masked) and the ID of the active one (active_id).

POST/settings/llm

Create an LLM configuration with provider (openai, anthropic, google, openrouter, nvidia, minimax, ant-ling or custom) and name (required, up to 100 characters). Optional: api_key, model, base_url, thinking_level (off, minimal, low, medium, high, xhigh, max) and the sampling fields temperature, top_p, top_k and max_tokens (unset means the provider default). A duplicate name returns 409.

GET/settings/llm/:id

Get one LLM configuration by numeric ID.

PUT/settings/llm/:id

Update name, api_key, model, thinking_level, base_url or a sampling field. Omitted fields keep their values; null resets a sampling field to the provider default. You cannot clear the API key of the active configuration.

DELETE/settings/llm/:id

Delete an LLM configuration.

PUT/settings/llm/:id/activate

Make an LLM configuration the active one for all agent runs. A configuration without an API key returns 400.

GET/settings/proxy

Get the outbound proxy settings: the masked proxy URL, no_proxy, and the per-service switches for llm, slack, zabbix, victoria_metrics, catchpoint, grafana, pagerduty, netbox, kubernetes and jira. SSH shows as unsupported.

PUT/settings/proxy

Update the proxy settings: proxy_url, no_proxy, and services.<name>.enabled for each service above.

GET/settings/retention

Get the data retention settings: enabled, retention_days (default 90) and cleanup_interval_hours (default 6).

PUT/settings/retention

Update the retention settings (enabled, retention_days, cleanup_interval_hours).

GET/settings/formatting

Removed. Returns 410 Gone; use /formatting-rules instead.

PUT/settings/formatting

Removed. Returns 410 Gone; create or update rules through /formatting-rules instead.

GET/formatting-rules

List the response-formatting rules in evaluation order. A rule can match on source kind, source UUID, channel UUID, last skill or a match expression, and then sets how the final answer is formatted.

POST/formatting-rules

Create a formatting rule with name (required) and optional match fields (empty means any), enabled (default true), system_prompt, output_schema_example, max_tokens (default 1500) and temperature (default 0.2). A schema example must be one valid top-level JSON object with no trailing values or text.

PUT/formatting-rules/reorder

Set the evaluation order: send uuids with every existing rule UUID exactly once.

PUT/formatting-rules/:uuid

Update any field of a formatting rule. Omitted fields keep their values; an empty match field clears that condition. A schema example must be one valid top-level JSON object with no trailing values or text.

DELETE/formatting-rules/:uuid

Delete a response-formatting rule.

Authentication and system

POST/auth/login

Exchange the admin username and password for a JWT. Returns token, username and expires_in (seconds). Wrong credentials return 401.

GET/auth/verify

Check the current JWT. Returns {"valid": true, "username": "..."}, or 401.

GET/auth/setup-status

Check whether the instance still needs the first-run admin setup (setup_required, setup_completed).

POST/auth/setup

Set the admin password on first run (password of at least 8 characters and a matching confirm_password). Returns a JWT like login. A validation error returns 422; after setup is complete, the call returns 403 with code setup_already_completed.

GET/health

Liveness check of the API server. Returns {"status": "ok", "version": "1.0.0"}; it does not check the database or the agent worker. The bundled proxy does not route this path, so call it on the API container (port 3000).

GET/system/status

Get the runtime state: whether the agent worker is connected, since when, and how many seconds ago it last sent a message.

Webhooks

POST/webhook/alert/:uuid

Receive alerts from a monitoring system. No JWT is needed. If the alert source has a webhook_secret, the request must carry it (where depends on the source type), or the call returns 401. A disabled source returns 403 and an unknown UUID returns 404.

API documentation

GET/docs

Interactive Swagger UI for the endpoints in the OpenAPI document.

GET/openapi.yaml

The OpenAPI 3.1 document in YAML.

Pagination

GET /incidents, GET /events and GET /proposals are paginated with the page and per_page query parameters. The defaults are page=1 and per_page=50; the maximum per_page is 200. Other list endpoints return all items as a plain JSON array.

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"

A paginated response wraps the items with metadata:

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

Example request

Submit a task
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 the likely root cause"
  }'

Versioning and deprecation

The base path /api serves API version 1. The version number is info.version in the OpenAPI document.

  • Additive changes are not breaking. New endpoints, new optional request fields, and new response fields ship inside the current version. Clients must ignore response fields they do not recognize and must not depend on property order.
  • Unknown request fields fail. Most endpoints reject a JSON body with a field they do not know with 400, so do not send fields that this page does not list.
  • Removed endpoints return 410 Gone. When an endpoint is retired, its route stays and answers 410 with an error message that names the replacement, for example /settings/slack, /settings/formatting and /skills/:name/tools. The server does not send Deprecation or Sunset headers.
Response from a removed endpoint
GET /api/settings/slack

HTTP/1.1 410 Gone
Content-Type: application/json

{"error":"/api/settings/slack has been removed; use /api/integrations and /api/channels"}
Read the changes between releases before you upgrade. Treat a 410 response as a signal to move to the endpoint that the error message names.

Rate limits

Akmatori does not limit the request rate and does not send rate-limit headers. The bundled proxy does not limit requests either. If a gateway, ingress or reverse proxy in front of Akmatori limits requests, that component sets the status code and headers. Many gateways use the standard fields below.

Rate-limit headers
HTTP/1.1 429 Too Many Requests
RateLimit: limit=100, remaining=0, reset=37
RateLimit-Policy: 100;w=60
Retry-After: 37
  • RateLimit — the current quota state: how many requests the window allows, how many remain, and how many seconds until it resets.
  • RateLimit-Policy — the window that produced those numbers.
  • Retry-After — seconds to wait before retrying.
On 429, wait at least Retry-After seconds, then back off exponentially with jitter. Treat it as backpressure, not as an error to escalate. No headers means "no advertised limit", not "unlimited".

Error responses

An error body is JSON: {"error": "message"}, with an optional machine-readable code and, for validation errors, a details object that maps field names to messages.

400Bad Request - invalid parameters, malformed JSON or an unknown field
401Unauthorized - missing, invalid or expired token
403Forbidden - the resource cannot be changed (for example a system or generated skill)
404Not Found - the resource does not exist
409Conflict - duplicate name, or the resource is in a state that does not allow the action
410Gone - the endpoint was removed; the message names the replacement
422Unprocessable Entity - field validation failed (see details), or a proposal failed to apply
429Too Many Requests - sent only by a gateway or proxy in front of Akmatori
500Internal Server Error - server error
503Service Unavailable - first-run setup is not complete (setup_required), or a needed service is not running