api

Slackzilla API Guide

Last updated at: 31/10/2026

The dashboard API is implemented by plain Node http handlers under server/api/. It is not an Express application. Each handler receives { req, res, url, context }, checks the method and path, writes a response, and returns true when it handled the request.

Section	Description
Response Envelope	Standard JSON response format for success and error responses.
Public Endpoints	Endpoints available to all clients, including status, telemetry, logs, commands, and the codebase assistant.
Admin Endpoints	Endpoints requiring the slackzilla_admin_session cookie, including feedback, control actions, and server events.
Terminal API	Bounded registered terminal commands and their permission model.
RAG Tools	Tool interfaces exposed to the repository-aware assistant.
Adding an Endpoint	Guide for adding new API endpoints, including request handling, response formatting, and error handling.
API Error Codes	List of error codes returned by the API, including status codes, error codes, descriptions, and source files.

Response Envelope

Successful JSON responses use:

{
    "ok": true,
    "data": {}
}

All API errors use the following response structure

{
    "ok": false,
    "code": "ERROR_CODE",
    "error": "Human-readable explanation"
}

with an additional fields depending on the error code.

Use context.sendOk() and context.sendError() in new handlers. Use context.parseBody(req) for JSON or URL-encoded bodies.

Public Endpoints

Method	Path	Purpose
GET	/api/status	Current bot, host, deployment, and runtime summary without telemetry history.
GET	/api/status/stream	SSE status updates without telemetry history.
GET	/api/telemetry	Current runtime telemetry and the last 120 samples.
GET	/api/telemetry/stream	SSE telemetry snapshots, including the last 120 samples.
GET	/api/metrics	Command totals, unique users/channels, and recent command activity.
GET	/api/logs	Bounded log snapshot as JSON.
GET	/api/logs/stream	SSE log snapshot and new log lines.
GET	/api/logs/download	Bounded raw log snapshot as plain text.
GET	/api/commands	Stable IDs and metadata for all commands.
GET	/api/commands/:id	Help and usage metadata for one command.
POST	/api/commands/:id	Execute an existing command and capture its response.
GET	/api/ask	Describes the assistant request format.
POST	/api/ask	Retrieves repository context and streams activity, optional tool calls, answer tokens, and completion data.
GET	/api/routes	Returns indexed repository HTTP routes.
GET	/api/release	Returns the current or requested release version, changes, and source file references.
GET	/api/session	Current authentication state, safe session metadata, and session CSRF token when authenticated.
POST	/api/terminal	Executes one registered terminal command; permission and authentication depend on the command.

Special Endpoints

These endpoints are separate from the /api/ modules. The webhook verifies its signature before processing a deployment request. The admin login creates the signed administrator session used by protected endpoints.

Method	Path	Purpose
POST	/webhook	Receives authenticated deployment notifications and triggers the configured deployment workflow.
POST	/admin/login	Authenticates an admin user and returns a session cookie.

Terminal API

POST /api/terminal accepts only registered terminal commands. It is rate limited and validates the command name and argument array before dispatching:

{
    "command": "logs",
    "args": ["--tail", "20"]
}

Limits are currently 4,096 characters for the logical input, 32 characters for the command name, 8 arguments per request, and 2,048 characters per argument. Arguments must be strings without control characters. Successful responses use the normal envelope:

{
    "ok": true,
    "data": {
        "command": "logs",
        "data": {}
    }
}

Public terminal commands include help, version, status, uptime, logs, api, docs, rag, and command. Administrative sudo operations require the current administrator session and CSRF validation. Mutating controls additionally use operation-bound master-password re-authentication and explicit confirmation. An internal POST submitted through the terminal does not bypass the destination API's own authentication, CSRF, confirmation, or rate-limit checks.

The browser terminal's api get and api post commands are same-origin helpers layered over existing /api/ routes. GET requests are allow-listed; POST requests may reach internal routes for normal users, but the destination handler remains authoritative. External URLs and arbitrary shell commands are not supported.

RAG Tools

The /api/ask assistant and npm run rag:use-tool expose these registered tools:

Tool	Purpose
getStatus	Read current status and deployment information.
runApiCommand	Call an internal /api/ route with GET or POST; external URLs and credential headers are rejected.
runTerminalCommand	Run a registered public terminal command; admin commands and shell execution are unavailable.
getCommands	List, filter, or inspect Slack command metadata.
getReleaseInfo	Read current or historical release information.
runCommand	Execute a registered Slack command, except blocked recursive AI commands.
getLogs	Read a bounded recent log view.
getErrors	Read bounded structured server errors; stacks are omitted unless requested by the tool interface.
getRoutes	List indexed repository HTTP routes.

Tool output is sanitized and bounded. runApiCommand accepts only internal /api/ paths and rejects headers containing credentials, cookies, CSRF values, passwords, secrets, tokens, or API keys. Tool execution does not grant administrator privileges; the target endpoint still enforces its normal controls.

Admin Endpoints

Admin endpoints require the slackzilla_admin_session cookie. State-changing requests additionally require the session CSRF token in X-CSRF-Token or the csrf body property.

Method	Path	Purpose
GET	/api/admin/summary	Admin status, feedback preview, deployment configuration, and logs.
GET	/api/admin/summary/stream	Streams admin summary updates over SSE.
GET	/api/admin/feedback	Search/filter feedback with q and status.
GET	/api/admin/feedback/:id	Read one feedback item.
GET	/api/admin/feedback/:id/replies	Read replies to a feedback item.
POST	/api/admin/feedback/:id	Mark read/unread, respond, or delete. Deletion requires confirmed: true.
POST	/api/admin/control	Authenticated administrative control actions for services, deployment, logs, telemetry, log archives, and event/error deletion.
GET	/api/admin/errors	Retrieves grouped server errors and their individual occurrence metadata.
GET	/api/admin/errors/stream	Streams server error updates over SSE.
GET	/api/admin/events	Retrieves grouped server events and their individual occurrence metadata.
GET	/api/admin/log-archives	Lists available log archives.

Example state-changing request:

{
    "action": "read",
    "csrf": "session-csrf-token"
}

Adding an Endpoint

See The API Extension Guide for details on adding new endpoints.

API Error Codes

Status	Error Code	Description	API Endpoint
400	BAD_REQUEST	The request could not be processed. This error is returned when an exception occurs while handling a feedback or control request.	/api/feedback, /api/admin/control
400	INVALID_FEEDBACK_ACTION	The requested feedback action is not recognised or is not supported by the feedback endpoint.	/api/feedback
400	INVALID_LOG_RANGE	The requested log range is invalid. The supplied range must meet the requirements of the log retrieval operation.	/api/admin/control
400	RESPONSE_REQUIRED	A response is required to complete the feedback action. The request cannot be processed without a response.	/api/feedback
400	RESPONSE_TOO_LONG	The submitted response exceeds the maximum permitted length of 4,000 characters. The response must be shortened before it can be submitted.	/api/feedback
400	UNKNOWN_CONTROL_ACTION	The requested control action is not recognised. The action must match one of the supported operations handled by the control endpoint.	/api/admin/control
403	CSRF_INVALID	The request failed CSRF validation because the token is missing or invalid. The request is rejected to protect the admin endpoint against cross-site request forgery.	/api/feedback, /api/admin/control
403	COMMAND_NOT_AVAILABLE	The requested command is not available for execution. The command may be disabled, restricted, or otherwise unavailable in the current context.	/api/commands
404	COMMAND_NOT_FOUND	The requested command could not be found. The command name or identifier may be invalid, or the command may not exist in the available command list.	/api/commands
404	FEEDBACK_NOT_FOUND	The requested feedback entry could not be found. The supplied feedback identifier does not correspond to an existing entry.	/api/feedback
404	RELEASE_NOT_FOUND	The requested release could not be found. The supplied release identifier does not match an available release.	/api/release
405	METHOD_NOT_ALLOWED	The HTTP method used in the request is not supported by the endpoint. The request must use a method accepted by the relevant route.	/api/ask, /api/commands, /api/feedback, /api/metrics, /api/routes, /api/release, /api/logs
409	CONFIRMATION_REQUIRED	The requested action requires explicit confirmation before it can proceed. This prevents potentially destructive operations from being executed without the required confirmation.	/api/feedback, /api/admin/control
409	FEEDBACK_DM_MISSING_USER	The feedback response was saved successfully, but the system could not send a Slack direct message because no associated Slack user ID was available.	/api/feedback
429	RATE_LIMITED	The request was rejected because the client has exceeded the allowed rate limit. The client must wait before making additional requests.	/api/commands, /api/ask
400	COMMAND_REQUIRED	A terminal command name was not supplied.	/api/terminal
400	COMMAND_INVALID	The terminal command name does not match the permitted command-name format.	/api/terminal
400	ARGUMENTS_INVALID	Terminal arguments must be an array of bounded strings without control characters.	/api/terminal
400	ARGUMENTS_TOO_MANY	The terminal request contains more than eight arguments.	/api/terminal
400	COMMAND_NOT_FOUND	The requested terminal command is not registered.	/api/terminal
401	AUTH_REQUIRED	The terminal command requires an authenticated administrator session.	/api/terminal
403	COMMAND_FORBIDDEN	The terminal command is not permitted for the current session.	/api/terminal
429	RATE_LIMITED	The terminal request exceeded its short request window or cooldown.	/api/terminal
500	ASK_FAILED	The assistant request failed while being processed. The server encountered an unexpected error and could not complete the request.	/api/ask
500	COMMAND_FAILED	The command request failed while being processed. The server encountered an error and could not return the expected command result.	/api/commands
500	CONTROL_ACTION_FAILED	The requested control action failed during execution. The server encountered an unexpected error while attempting to perform the operation.	/api/admin/control
500	LOG_RETRIEVAL_FAILED	The server could not retrieve the requested logs. An error occurred while accessing or processing the log data.	/api/logs
500	METRICS_RETRIEVAL_FAILED	The server could not retrieve metrics. An error occurred while collecting or processing the requested metrics data.	/api/metrics
502	FEEDBACK_DM_FAILED	The feedback response was saved successfully, but delivery of the Slack direct message failed. The notification could not be delivered even though the response itself was recorded.	/api/feedback