HTTP and ConnectRPC API reference
stromboli serves everything on one port (STROMBOLI_ADDR, default :8080), in plain HTTP/1.1 and unencrypted HTTP/2. TLS is expected to be terminated in front of it.
HTTP routes
| Route |
Auth |
|
/stromboli.v1.<Service>/<Method> |
API token |
the ConnectRPC API |
/grpc.health.v1.Health/* |
none |
gRPC health checks for the four services |
/grpc.reflection.v1.ServerReflection/*, /grpc.reflection.v1alpha.ServerReflection/* |
none |
gRPC server reflection |
POST /webhooks/{openstatus,alertmanager,grafana,generic} |
webhook token |
alert webhooks |
POST /slack/interactions |
Slack request signature |
Apply/Reject buttons; only with SLACK_SIGNING_SECRET, Slack and actions enabled |
/mcp |
MCP token or API token |
MCP over HTTP; only with STROMBOLI_MCP_ENABLED=true |
GET /healthz |
none |
200 ok when Postgres answers a ping, else 503 database unavailable |
Authentication
Every RPC needs Authorization: Bearer <STROMBOLI_API_TOKEN>. A wrong or missing token returns unauthenticated (invalid or missing API token). When STROMBOLI_API_TOKEN is empty, the API is open and the server logs a warning on startup.
Protocols
The services are defined in proto/stromboli/v1 and served with ConnectRPC. Each endpoint speaks the Connect protocol (including plain JSON over HTTP POST), gRPC and gRPC-Web:
curl -H "Authorization: Bearer $STROMBOLI_API_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"api"}' localhost:8080/stromboli.v1.CatalogService/GetService
grpcurl -plaintext -H "Authorization: Bearer $STROMBOLI_API_TOKEN" localhost:8080 list
RPCs marked no side effects can also be called with Connect GET requests. JSON uses the protobuf JSON mapping: field names in lowerCamelCase (proto names are accepted on input), int64 as strings, timestamps in RFC 3339.
The API stays backwards compatible across releases (buf breaking runs on every change).
ConnectRPC services
CatalogService
| RPC |
|
Errors |
ListServices |
every service, sorted by name. No side effects |
|
GetService(name) |
the service, plus its upstream and downstream service names. No side effects |
not_found |
UpsertService(service) |
create or replace one service; returns validation issues (warnings) |
invalid_argument when the resulting catalog has errors |
DeleteService(name) |
|
not_found |
ImportCatalog(services_yaml, runbooks, prune, dry_run) |
upsert services and runbooks from YAML; with prune, delete those not in the request. Returns counts and issues |
invalid_argument when the catalog has errors |
ExportCatalog |
services_yaml and every runbook. No side effects |
|
ValidateCatalog(check_connectors) |
issues of the stored catalog; with check_connectors, a test query per selector. No side effects |
|
DiscoverServices(connector) |
proposed candidates from a log or metrics connector. No side effects |
failed_precondition for an unknown or unsupported connector |
ConnectorService
| RPC |
|
Errors |
CreateConnector(name, kind, config, replace) |
validate keys, encrypt secrets, store. Returns the connector without secret values |
invalid_argument (unknown kind or key, missing required key), already_exists without replace |
ListConnectors |
every connector; secret keys are listed with an empty value. No side effects |
|
DeleteConnector(name) |
|
not_found |
TestConnector(name) |
ok and a message: a failed check is ok: false, not an RPC error. No side effects |
|
InvestigationService
| RPC |
|
Errors |
StartInvestigation(service, title, description) |
start an investigation (source manual, title default Manual investigation of <service>) and return it right away, status running |
invalid_argument without service; failed_precondition when no LLM is configured or the service is not in the catalog |
GetInvestigation(id) |
the investigation and all its steps. No side effects |
invalid_argument (bad UUID), not_found |
ListInvestigations(limit) |
newest first; limit defaults to 50, at most 200. No side effects |
|
WatchInvestigation(id, after_seq) |
server stream: every step with seq > after_seq as it is recorded, then one finished event with the investigation, then the stream ends. Polls every second |
not_found |
GetBrief(service, since) |
the Markdown brief, built without the LLM. since defaults to 1h, at most 168h. No side effects |
invalid_argument (bad duration), failed_precondition (unknown service) |
StartInvestigation called by the MCP server is recorded with source mcp and the client’s name in the alert (mcp_client).
ActionService
| RPC |
|
Errors |
ListActions(investigation_id, status, limit) |
newest first; limit defaults to 50, at most 200. No side effects |
invalid_argument (bad UUID) |
GetAction(id) |
No side effects |
not_found |
ApproveAction(id, approver, note) |
re-validate, claim and run the action synchronously; returns it succeeded or failed |
not_found; failed_precondition when it is not proposed, has expired, no approver was given, or can no longer run |
RejectAction(id, approver, reason) |
|
not_found; failed_precondition when it is not proposed |
Messages
Investigation
| Field |
Type |
|
id |
string |
UUID |
title |
string |
|
source |
string |
manual, mcp, openstatus, alertmanager (also for Grafana), webhook, healthcheck |
services |
string[] |
|
status |
enum |
INVESTIGATION_STATUS_RUNNING, _COMPLETED, _FAILED |
alert |
object |
the alert payload, plus description and observed_at |
mitigation |
Mitigation |
set as soon as triage proposes it |
mitigated_at |
timestamp |
when the first mitigation was proposed |
report |
Report |
set when completed |
error |
string |
set when failed |
created_at, finished_at |
timestamp |
|
input_tokens, output_tokens |
int64 |
totals over every model turn (input includes cache reads and writes) |
Mitigation
| Field |
|
kind |
rollback, restart, scale_up, drain, disable_feature, block_traffic, failover, degrade or none |
target |
what it applies to: service, deploy SHA, region, instance, flag, dependency |
action |
the exact command(s) a human runs |
rationale |
why it fits the symptoms |
verify |
how to tell it worked |
undo |
how to revert it |
risk |
safe, reversible or destructive |
confidence |
low, medium or high |
impact |
current user impact |
machine_action |
MachineAction, when stromboli can run it after approval |
action_id |
ID of the Action created for machine_action |
Report
| Field |
|
summary |
what is happening, in one sentence |
likely_cause |
the most likely cause, or unknown |
confidence |
low, medium or high |
evidence |
observations backing the cause |
ruled_out |
hypotheses checked and rejected, with the reason |
suggested_mitigation |
the mitigation in light of the cause: confirmed, what to do instead, or none |
fix |
the long-term fix, or unknown |
next_steps |
what a human should check next |
Step
One entry of an investigation’s audit trail.
| Field |
|
seq |
position in the investigation, increasing |
kind |
brief, tool_call, llm, mitigation, report or error |
name |
the service (brief), tool (tool_call), model (llm) or mitigation kind (mitigation) |
input |
the tool input (tool_call); turn, task, model, stop reason and token counts (llm) |
output |
the brief, tool result, model text, mitigation or report JSON, or error |
is_error |
the step failed |
duration_ms, created_at |
|
MachineAction
| Field |
|
service |
catalog service |
action |
restart, clone, cordon, uncordon, stop or start |
machine_ids |
machines to act on |
region |
clone only: region of the new machines; default the source’s |
app |
Fly app, resolved from the catalog |
Action
| Field |
|
id, investigation_id, service |
|
machine_action |
MachineAction |
connector |
the fly_machines connector that runs it |
status |
ACTION_STATUS_PROPOSED, _RUNNING, _SUCCEEDED, _FAILED, _REJECTED, _EXPIRED, _SUPERSEDED |
decided_by, note |
who approved or rejected it, and their note |
result |
what was done machine by machine, and how to undo it |
error |
|
created_at, expires_at, decided_at, finished_at |
|
Service, Runbook, ValidationIssue, Connector
See the catalog reference and connectors reference. A ValidationIssue has service, field, message and warning (false = error).
Edit this page on GitHub ↗