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.
# 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/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
https://your-akmatori-instance/api/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
/incidentsList incidents, newest first, with pagination (page, per_page) and optional filters: from and to (Unix seconds, on creation time) and status (comma-separated).
/incidents/:uuidGet an incident by UUID, with its agent runs, latest response, full log, token count and execution time.
/incidents/:uuid/alertsList the normalized alerts linked to an incident, oldest first, with their firing or resolved state.
/incidents/:uuid/responseGet only the latest agent response of an incident (uuid, title, status, response), without the log.
/incidentsSubmit 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.
/incidents/:uuid/closeClose 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.
/incidents/:uuid/feedbackSend 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.
/incidents/sweep-staleRun 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.
/requests/:uuidGet 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.
/requests/:uuid/responseGet only the latest response of a request, without the log.
Alert lifecycle
/alerts/:uuid/unlinkUnlink 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.
/alerts/:uuid/moveMove 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.
/alerts/:uuid/resolveMark a firing alert as resolved without waiting for a resolved webhook from its source. An alert that is already resolved returns 409.
Events
/eventsList 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).
/events/rawGet the raw payload and original message of one event: ?uuid=<event_uuid> (required).
Skills
/skillsList all skills.
/skillsCreate a skill with name (required, up to 64 characters) and optional description, category and prompt.
/skills/:nameGet a skill and its prompt by name.
/skills/:nameUpdate description, category, enabled or prompt. Other fields are ignored. The generated connected-tools skill returns 403.
/skills/:nameDelete a skill. System skills return 403.
/skills/:name/promptGet the prompt of a skill.
/skills/:name/promptReplace the prompt of a skill ({"prompt": "..."}).
/skills/:name/toolsRetired: 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).
/skills/:name/scriptsList the scripts of a skill.
/skills/:name/scriptsDelete all scripts of a skill.
/skills/:name/scripts/:filenameGet one script by file name.
/skills/:name/scripts/:filenameCreate or replace a script.
/skills/:name/scripts/:filenameDelete one script.
/skills/syncLoad skills from the file system into the database.
Connectors
/connectorsList 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.
/connectors/catalogList every kind of connector that can be added, with its capabilities and the tool types, alert source types or messaging provider it accepts.
/connectors/lookupFind the connector of a part: ?kind=tool_instance|alert_source|integration|mcp_server&id=N returns connector_uuid.
/connectors/:uuidGet a connector with its parts: tool instances, alert sources (with last alert time), integrations (with channel counts) and the MCP server.
/connectors/:uuidRename a connector ({"name": "..."}). PUT works too.
/connectors/:uuidDelete 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.
/connectors/:uuid/partsMove 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.
/connectors/:uuid/parts/:kind/:idMove a part out into a new connector of its own. Returns the new connector_uuid.
Tools
/tool-typesList the tool types.
/toolsList the tool instances. Secret settings are masked and SSH private keys are left out.
/toolsCreate 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.
/tools/:idGet a tool instance. Secret settings are masked.
/tools/:idUpdate 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.
/tools/:idDelete a tool instance. The tool instance that belongs to an MCP server returns 409; change it through /mcp-servers.
/tools/:id/ssh-keysList the SSH keys of an SSH tool (without the private keys).
/tools/:id/ssh-keysAdd an SSH key with name and private_key (required) and optional is_default.
/tools/:id/ssh-keys/:keyIdChange the name or is_default of an SSH key.
/tools/:id/ssh-keys/:keyIdDelete an SSH key.
Alert sources
/alert-source-typesList the alert source types you can create. Deprecated types are not listed.
/alert-sourcesList the alert sources.
/alert-sourcesCreate 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.
/alert-sources/:uuidGet an alert source by UUID.
/alert-sources/:uuidUpdate 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.
/alert-sources/:uuidDelete an alert source. Its webhook URL stops working.
Messaging integrations
/integrationsList messaging provider integrations (slack, telegram, discord), with credentials masked in responses.
/integrationsCreate 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.
/integrations/:uuidGet an integration by UUID. Secret credentials are masked.
/integrations/:uuidUpdate name, credentials or enabled. A blank or omitted secret keeps the stored value. You cannot change the provider.
/integrations/:uuidDelete a messaging integration and its channels.
/integrations/:uuid/testCheck the stored credentials with the provider (Slack auth.test, Telegram getMe, Discord /users/@me). Returns {"ok", "account", "error"}.
Channels
/channelsList channels, with optional filters integration_uuid, can_post and can_listen.
/channelsCreate 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.
/channels/:uuidGet a channel by UUID, with its integration (credentials masked).
/channels/:uuidUpdate any of the channel fields above except integration_uuid. Omitted fields keep their values.
/channels/:uuidDelete a channel. Akmatori reloads the Slack listener routing.
Cron jobs
/cron-jobsList scheduled agent jobs, with the target channel, next run time, system flag, last-run status, tools_enabled and builtin_tools.
/cron-jobsCreate 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.
/cron-jobs/:uuidGet a scheduled job, including last-run status, next run time, delivery target, system flag, tools_enabled and builtin_tools.
/cron-jobs/:uuidUpdate name, schedule, prompt, channel_uuid (an empty string clears it), enabled, post_results, tools_enabled or builtin_tools. Omitted fields keep their stored values.
/cron-jobs/:uuid/runStart a job immediately in the background and return 202 Accepted.
/cron-jobs/:uuidDelete a scheduled job that an operator created. System jobs return 409 Conflict; disable them with PUT instead.
Context files
/contextList all context files.
/contextUpload 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.
/context/:idGet the metadata of a context file.
/context/:id/downloadDownload the content of a context file.
/context/:idDelete a context file.
/context/:id/summarizeRun the summary of a context file again, for example after a failure. Returns 202 with the file.
/context/validateCheck the context file references in a text ({"text": "..."}). Returns valid, references, found and missing.
Runbooks
/runbooksList all runbooks.
/runbooksCreate a runbook (title, content). The agent can find it at once with the runbooks.search tool.
/runbooks/:idGet a runbook by ID.
/runbooks/:idUpdate the title and content of a runbook.
/runbooks/:idDelete a runbook.
Cross-incident memory
/memoriesList 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).
/memoriesCreate 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.
/memories/scopesList the scopes that have at least one memory.
/memories/:idGet a single memory by ID, with its evidence grade, usage counts, and resolved [[...]] references.
/memories/:idUpdate a memory. Omitted fields keep their stored values; send "body": "" to clear the body.
/memories/:idDelete a memory. Returns 204.
/memories/from-textCreate 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.
/memories/exportDownload all memories as a zip of <scope>/<name>.md files.
/incidents/:uuid/extract-memoryRun 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.
/incidents/extract-memory-backfillQueue 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
/proposalsList improvement proposals, with pagination and optional status and kind filters.
/proposals/countGet the number of pending proposals ({"pending": n}).
/proposals/:uuidGet one proposal, with its reasoning, the current content of the target and the proposed content.
/proposals/:uuid/approveApprove 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.
/proposals/:uuid/rejectReject a proposal.
/proposals/:uuid/chatGet the review chat of a proposal: messages, chat_incident_uuid and chat_status (poll while it is running).
/proposals/:uuid/chatSend 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
/http-connectorsList the HTTP connectors (tool types that call an external HTTP API).
/http-connectorsCreate 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.
/http-connectors/:idGet an HTTP connector by ID.
/http-connectors/:idUpdate tool_type_name, description, base_url_field, auth_config, tools or enabled. Omitted fields keep their values.
/http-connectors/:idDelete an HTTP connector.
MCP servers (custom connectors)
/mcp-serversList 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.
/mcp-serversAdd 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.
/mcp-servers/:idGet an MCP server (secrets masked).
/mcp-servers/:idUpdate 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.
/mcp-servers/:idDelete an MCP server with its managed tool instance and tool type.
/mcp-servers/testTest 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.
/mcp-servers/:id/testTest a stored server. Optional url and auth_config override the stored values one by one.
/mcp-servers/statusGet the gateway connection status of every MCP server: connected, tool count, tool names and last error.
/mcp-servers/:id/oauth/startStart 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).
/mcp-servers/:id/oauth/disconnectForget the OAuth tokens of a server (the client registration is kept).
/mcp-servers/oauth/callbackPublic OAuth redirect target. Exchanges the code and returns to the connector page with ?oauth=connected or ?oauth_error=….
Settings
/settings/generalGet the general settings: the base URL for links in notifications, alert correlation, event classification, incident merge and auto-close, and memory generation.
/settings/generalUpdate 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.
/settings/slackRemoved. Returns 410 Gone; use /integrations and /channels instead.
/settings/slackRemoved. Returns 410 Gone; set up Slack through messaging integrations and channels.
/settings/llmList all LLM configurations (configs, API keys masked) and the ID of the active one (active_id).
/settings/llmCreate 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.
/settings/llm/:idGet one LLM configuration by numeric ID.
/settings/llm/:idUpdate 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.
/settings/llm/:idDelete an LLM configuration.
/settings/llm/:id/activateMake an LLM configuration the active one for all agent runs. A configuration without an API key returns 400.
/settings/proxyGet 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.
/settings/proxyUpdate the proxy settings: proxy_url, no_proxy, and services.<name>.enabled for each service above.
/settings/retentionGet the data retention settings: enabled, retention_days (default 90) and cleanup_interval_hours (default 6).
/settings/retentionUpdate the retention settings (enabled, retention_days, cleanup_interval_hours).
/settings/formattingRemoved. Returns 410 Gone; use /formatting-rules instead.
/settings/formattingRemoved. Returns 410 Gone; create or update rules through /formatting-rules instead.
/formatting-rulesList 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.
/formatting-rulesCreate 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.
/formatting-rules/reorderSet the evaluation order: send uuids with every existing rule UUID exactly once.
/formatting-rules/:uuidUpdate 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.
/formatting-rules/:uuidDelete a response-formatting rule.
Authentication and system
/auth/loginExchange the admin username and password for a JWT. Returns token, username and expires_in (seconds). Wrong credentials return 401.
/auth/verifyCheck the current JWT. Returns {"valid": true, "username": "..."}, or 401.
/auth/setup-statusCheck whether the instance still needs the first-run admin setup (setup_required, setup_completed).
/auth/setupSet 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.
/healthLiveness 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).
/system/statusGet the runtime state: whether the agent worker is connected, since when, and how many seconds ago it last sent a message.
Webhooks
/webhook/alert/:uuidReceive 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
/docsInteractive Swagger UI for the endpoints in the OpenAPI document.
/openapi.yamlThe 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.
# 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:
{
"data": [...],
"pagination": {
"page": 2,
"per_page": 25,
"total": 147,
"total_pages": 6
}
}Example request
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 answers410with an error message that names the replacement, for example/settings/slack,/settings/formattingand/skills/:name/tools. The server does not sendDeprecationorSunsetheaders.
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"}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.
HTTP/1.1 429 Too Many Requests
RateLimit: limit=100, remaining=0, reset=37
RateLimit-Policy: 100;w=60
Retry-After: 37RateLimit— 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.
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 field401Unauthorized - missing, invalid or expired token403Forbidden - the resource cannot be changed (for example a system or generated skill)404Not Found - the resource does not exist409Conflict - duplicate name, or the resource is in a state that does not allow the action410Gone - the endpoint was removed; the message names the replacement422Unprocessable Entity - field validation failed (see details), or a proposal failed to apply429Too Many Requests - sent only by a gateway or proxy in front of Akmatori500Internal Server Error - server error503Service Unavailable - first-run setup is not complete (setup_required), or a needed service is not running