REST API
The web app uses the SREInsights REST API for everything it does, and you can use the same API from scripts, CI pipelines and other tools. This page lists every endpoint under /api/v1, grouped by area, with the request bodies and error codes that matter.
Runners use a separate API, /runner/v1. It is described in Runner protocol.
Base URL
Section titled “Base URL”https://console.sreinsights.com/api/v1
On a self-hosted instance, use <your SREInsights URL>/api/v1.
Every request and response body is JSON. Send content-type: application/json with a body. A request body may be at most 1 MB.
Responses
Section titled “Responses”A successful call answers with status: "success" and the result in data:
{ "status": "success", "data": { "id": "0193…", "name": "Checkout API" } }Calls that create something answer 201. Calls that queue work for later (Run now, Backfill, a report send, a webhook trigger) answer 202. A delete answers 200 with "data": null.
Every response carries an x-request-id header. Send your own x-request-id (8–64 letters, digits, _ or -) to correlate a call with your logs; otherwise SREInsights makes one.
Authentication
Section titled “Authentication”Most endpoints need a signed-in user and an active organization. You sign in with an email and password, and get back two tokens:
| Token | Where it is | Lifetime | What it is for |
|---|---|---|---|
| Access token | data.accessToken in the response body |
15 minutes by default (SREINSIGHTS_ACCESS_TOKEN_TTL_S) |
Send it on every call as Authorization: Bearer <access token>. |
| Refresh token | An HttpOnly, SameSite=Strict cookie named sreinsights_rt, scoped to /api/v1/auth |
30 days by default (SREINSIGHTS_REFRESH_TOKEN_TTL_DAYS) |
Trade it for a new access token with POST /auth/refresh. |
The cookie is marked Secure when the instance’s URL starts with https://. The lifetimes above are set by the operator; see Environment variables.
Sign in
Section titled “Sign in”POST /auth/login with { "email": "...", "password": "..." }. A wrong email or password, or a deactivated account, all answer 401 INVALID_CREDENTIALS.
Refresh
Section titled “Refresh”When a call answers 401 TOKEN_EXPIRED, call POST /auth/refresh with the refresh cookie. You get a new access token and a new refresh cookie: each refresh token works once. A refresh token that is unknown, revoked or expired answers 401 REFRESH_INVALID, and the cookie is cleared. Sign in again.
Active organization
Section titled “Active organization”An access token carries one active organization. Sign-in picks the first organization you joined. To work in another one:
- List your organizations with
GET /auth/me(fieldorgs) orGET /orgs/summary. - Call
POST /orgs/switchwith{ "orgId": "<org id>" }. - Use the
accessTokenit returns from then on.
An organization you are not a member of answers 404 NOT_FOUND. A refresh keeps the organization you switched to, as long as you are still a member.
Endpoints that read or write an organization’s data answer 409 NO_ACTIVE_ORG when the token has no active organization (for example, you were removed from your last one).
Authentication errors
Section titled “Authentication errors”| Status | Code | What it means |
|---|---|---|
| 401 | UNAUTHENTICATED |
No Authorization: Bearer header. |
| 401 | TOKEN_EXPIRED |
The access token expired. Refresh it. |
| 401 | TOKEN_INVALID |
The token is malformed or not signed by this instance. Sign in again. |
| 401 | TOKEN_REVOKED |
The session ended: you signed out, changed your password, or your account was deactivated. Sign in again. |
| 403 | ORG_ACCESS_REVOKED |
You are no longer a member of the token’s organization, or it was deleted. Switch organizations. |
| 409 | NO_ACTIVE_ORG |
The endpoint needs an organization and the token has none. |
Sessions are checked on every call, so a sign-out or password change takes effect at once, not when the access token expires.
Other ways to authenticate
Section titled “Other ways to authenticate”Three endpoints don’t take a user’s token. Each uses a token of its own:
| Endpoint | Token |
|---|---|
POST /hooks/{triggerId} |
The webhook trigger’s pwt_… token. See Webhooks. |
POST /ingest/{type}/{connectionId} |
The connection’s pit_… ingest token. See Ingest. |
GET /public/status/{token} |
None: the token in the address is the key. See Status pages. |
Errors
Section titled “Errors”Every error has the same shape:
{ "status": "fail", "code": "VALIDATION_FAILED", "message": "Some fields are missing or invalid", "details": [{ "path": "schedule.cron", "message": "Required" }], "requestId": "4f1c2b8e-…"}| Field | What it is |
|---|---|
status |
fail for a 4xx answer, error for a 5xx answer. |
code |
A stable machine-readable code. Branch on this, not on message. |
message |
A sentence you can show to a person. |
details |
Present on some errors. For VALIDATION_FAILED, a list of { path, message }, one per field. |
requestId |
The same value as the x-request-id header. Quote it when you report a problem. |
These codes can come from any endpoint:
| Status | Code | What it means |
|---|---|---|
| 400 | VALIDATION_FAILED |
A field is missing or invalid. details names each one. |
| 400 | BAD_REQUEST |
The body is not valid JSON. |
| 403 | POLICY_DENIED |
Your role doesn’t allow this action. See Organizations and roles. |
| 404 | NOT_FOUND |
No such record in your organization. A record in another organization or client also answers 404, never 403. |
| 404 | ROUTE_NOT_FOUND |
There is no endpoint with this method and path. |
| 409 | ALREADY_EXISTS |
A record with these values already exists, for example a runner group with the same name. |
| 409 | IN_USE |
Other records still depend on this one. Move or delete them first. |
| 413 | PAYLOAD_TOO_LARGE |
The request body is larger than 1 MB. |
| 500 | INTERNAL |
Something failed on the server. Try again, and quote the requestId if it keeps happening. |
Each area below lists the codes its endpoints add.
Pagination and limits
Section titled “Pagination and limits”The API has no page cursors. Lists return everything up to a fixed cap: monitors up to 1,000, silences up to 500.
Three history endpoints take a limit and, where shown, a before time to page back:
| Endpoint | limit |
before |
|---|---|---|
GET /monitors/{id}/results |
1–200, default 50 | ISO date-time; results that finished before it |
GET /jobs/{id}/runs |
1–200, default 50 | ISO date-time; runs created before it |
GET /alerts |
1–200, default 50 | Not supported |
To page back, pass the oldest finishedAt (results) or createdAt (runs) you got as before.
Rate limits
Section titled “Rate limits”Only the public status page endpoint is rate limited: 60 requests per minute per client address, and 1,200 per minute in all, counted per server process. Over the limit, it answers 429 with a plain-text body and a retry-after header in seconds.
The AI endpoints pass on the AI service’s own limit as 429 AI_RATE_LIMITED.
Auth and account
Section titled “Auth and account”| Method | Path | What it does |
|---|---|---|
| POST | /auth/signup |
Public. Creates an account and a new organization with you as Owner. Answers 201 with an access token and the refresh cookie. |
| POST | /auth/login |
Public. Signs in. Answers with an access token and the refresh cookie. |
| POST | /auth/refresh |
Public (needs the refresh cookie). A new access token and refresh cookie. |
| POST | /auth/logout |
Ends this session and clears the refresh cookie. |
| GET | /auth/me |
You, your organizations (with your role in each), the active organization, its plan, and which pages your role may see. |
| POST | /auth/password |
Changes your password. Your other sessions are signed out; this one gets a new access token and cookie. |
| POST | /auth/delete-account |
Deletes your account for good. |
| GET | /auth/reset?token=… |
Public. Who a password reset link is for. |
| POST | /auth/reset |
Public. Sets a new password from a reset link and signs you in. |
| GET | /auth/invite?token=… |
Public. Who an invitation is for. |
| POST | /auth/accept-invite |
Public, or signed in as the invited email. Joins the organization and answers with a session in it. |
Request bodies:
| Endpoint | Body |
|---|---|
POST /auth/signup |
{ "email", "password", "name", "orgName" } |
POST /auth/login |
{ "email", "password" } |
POST /auth/password |
{ "currentPassword", "newPassword" } |
POST /auth/delete-account |
{ "password" } |
POST /auth/reset |
{ "token", "password" } |
POST /auth/accept-invite |
{ "token", "name"?, "password"? }. name and password are needed when the invited email has no account yet. Answers 201 when it created the account, 200 otherwise. |
Passwords must be at least 10 characters.
| Status | Code | When |
|---|---|---|
| 400 | PASSWORD_TOO_SHORT |
A new password is under 10 characters. |
| 400 | INVALID_CREDENTIALS |
The current password is wrong (password change, account deletion). |
| 400 | PASSWORD_UNCHANGED |
The new password is the same as the current one. |
| 400 | ACCOUNT_DETAILS_REQUIRED |
Accepting an invitation without an account, and name or password is missing. |
| 401 | INVALID_CREDENTIALS |
Sign-in failed. |
| 404 | INVITE_INVALID, RESET_INVALID |
The invitation or reset link was used, revoked or never existed. |
| 409 | EMAIL_TAKEN |
An account with this email already exists. |
| 409 | SIGN_IN_TO_ACCEPT |
The invited email has an account: sign in as it, then accept. |
| 409 | LAST_OWNER |
You are the only Owner of an organization. Make someone else Owner first. |
| 410 | INVITE_EXPIRED, RESET_EXPIRED |
The link expired. Ask for a new one. |
Organizations and members
Section titled “Organizations and members”| Method | Path | What it does |
|---|---|---|
| GET | /orgs/summary |
Every organization you belong to, with its health counts. Needs a session, not an active organization. |
| POST | /orgs/switch |
Makes another organization active. Body { "orgId" }. Answers { "accessToken" }. |
| GET | /members |
The active organization’s members and open invitations. |
| GET | /roles |
Every role, each with assignable: whether your role may give it. |
| POST | /members |
Adds a member by email. Body { "email", "role" }. |
| PATCH | /members/{userId} |
Changes a member’s role, or the clients they are limited to. Body { "role"?, "clientIds"? }. |
| POST | /members/{userId}/reset-password |
Makes a one-time password reset link for a member, valid for 24 hours. Shown once. |
| DELETE | /members/{userId} |
Removes a member from the organization. |
| DELETE | /invites/{id} |
Revokes an open invitation. |
POST /members answers 201 in one of two ways:
- The email already has an account: they join at once, and
data.joinedistrue. - It doesn’t:
data.joinedisfalseanddata.linkis a one-time/join?token=…link, valid for 7 days. Send it to them yourself.
In PATCH /members/{userId}, clientIds: [] means every client. Owners and Admins always see every client. See Clients.
| Status | Code | When |
|---|---|---|
| 400 | UNKNOWN_ROLE |
No role with that name. |
| 400 | CLIENT_LIMIT_NOT_APPLICABLE |
You tried to limit an Owner or Admin to some clients. |
| 400 | UNKNOWN_CLIENT |
One of clientIds is not in this organization. |
| 403 | POLICY_DENIED |
Your role can’t manage members, or can’t grant or change a role above your own. |
| 409 | ALREADY_MEMBER |
The email is already a member. |
| 409 | LAST_OWNER |
The change would leave the organization without an Owner. |
Runner groups and runners
Section titled “Runner groups and runners”| Method | Path | What it does |
|---|---|---|
| GET | /runner-group-kinds |
Which kinds of runner group this instance offers: polling, and lambda when the operator switched Lambda runner groups on. |
| GET | /runner-groups |
Your runner groups, each with its runners and their status. |
| GET | /hosted-runner-groups |
Hosted runner locations every organization may use. Read-only: the operator runs them. |
| POST | /runner-groups |
Creates a runner group. |
| PATCH | /runner-groups/{id} |
Changes the description, or a Lambda group’s function. |
| DELETE | /runner-groups/{id} |
Deletes a group no monitor runs on. |
| POST | /runner-groups/{id}/registration-tokens |
Makes a one-time registration token (prt_…) and the install command. The token is shown once. |
| POST | /runners/{id}/disable |
Disables a runner. Its running work goes back to the group at once. Answers { "disabled": true, "requeuedRuns" }. |
POST /runner-groups body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
name |
string | Yes | Lower-case letters, digits, ., _ or -, up to 63 characters. |
|
description |
string | No | Up to 500 characters. | |
kind |
polling or lambda |
No | polling |
Fixed once the group exists. |
lambda |
object | For lambda |
{ "functionName", "region" }. functionName is a name, name:alias or a function ARN. |
POST /runner-groups/{id}/registration-tokens body (optional):
| Field | Type | Default | What it does |
|---|---|---|---|
uses |
integer, 1–50 | 1 | How many runners may register with the token. |
expiresInHours |
integer, 1–168 | 24 | When the token stops working. |
The response holds token, group, usesLeft, expiresAt and install. For a polling group, install.docker is a ready docker run command. For a Lambda group, install.lambda.identityCommand registers the function once and prints its identity; see Set up a Lambda runner.
Each runner in GET /runner-groups has a status: online (it called in during the last 60 seconds), offline, disabled, or on_demand for a Lambda group’s function. A group’s redundant is true when two or more of its runners are online.
| Status | Code | When |
|---|---|---|
| 400 | LAMBDA_RUNNERS_DISABLED |
Lambda runner groups aren’t switched on for this instance. |
| 400 | LAMBDA_ROLE_NOT_SUPPORTED |
You sent roleArn or externalId. Invoking a function through a role in another AWS account isn’t available. |
| 400 | NOT_A_LAMBDA_GROUP |
You sent lambda for a polling group. |
| 409 | IN_USE |
Monitors still run on the group. Move them first. |
| 409 | ALREADY_EXISTS |
A group with this name exists. |
Monitors
Section titled “Monitors”| Method | Path | What it does |
|---|---|---|
| GET | /monitors |
All monitors, by name. |
| POST | /monitors |
Creates a monitor and its schedule. |
| GET | /monitors/{id} |
One monitor. |
| PATCH | /monitors/{id} |
Changes any of the fields below. Send only what changes. |
| DELETE | /monitors/{id} |
Deletes a monitor. Its schedule and webhook triggers stop at once. |
| POST | /monitors/{id}/run |
Run now: queues one run, even while the monitor is paused. Answers 202. |
| GET | /monitors/{id}/results |
Results, newest first. Takes limit and before. |
POST /monitors body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
name |
string | Yes | Up to 120 characters. | |
description |
string | No | Up to 2,000 characters. | |
clientId |
uuid | No | The client it belongs to. Leave out for the organization’s own. | |
enabled |
boolean | No | true |
false pauses the schedule. |
definition |
object | Yes | What to check. See Check types and Flow steps. | |
parameters |
array | No | [] |
Inputs each run receives as params.<name>. See Monitors. |
runsOn |
object | Yes | { "group": "<group name or id>", "labels": [] }. A hosted location’s name works too. |
|
schedule |
object | Yes | { "cron", "timezone": "UTC", "inputs": {} }. inputs are parameter values for scheduled runs. |
|
labels |
object | No | {} |
Up to 30 name: value pairs. Names are lower-case letters, digits and _. |
The cron expression takes 5 fields, 6 with seconds, or a macro such as @hourly. The timezone is an IANA name such as Europe/Berlin.
PATCH /monitors/{id} with "enabled": false also resolves the monitor’s open alerts. Leaving schedule.inputs out of a PATCH keeps the current values.
POST /monitors/{id}/run body: { "params": { … } } (optional). The run uses the schedule’s inputs, overridden by params. It answers { "jobId", "status": "queued", "queueExpiresAt", "params" }. A queued run waits up to 5 minutes for a runner.
A monitor’s activeRun is null, or { "state": "waiting_for_runner" | "running", "since" }.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_SCHEDULE |
The cron expression or timezone doesn’t parse, or the schedule never runs. |
| 400 | SCHEDULE_TOO_FREQUENT |
The schedule runs more often than every 30 seconds, or more often than this instance allows. |
| 400 | UNKNOWN_RUNNER_GROUP |
runsOn.group names no group of yours and no hosted location. |
| 400 | UNKNOWN_CLIENT |
clientId is not in this organization. |
| 400 | JOB_TYPE_ON_MONITOR |
The definition is a data job. Create it with POST /jobs. |
| 400 | HOSTED_SCRIPT_NOT_ALLOWED |
The monitor runs on a hosted location and uses a script. |
| 400 | HOSTED_RUNNER_LOCAL_SECRETS |
A connection keeps its secrets on your runners, so hosted runners can’t use it. |
| 400 | LAMBDA_DOCKER_SCRIPT_NOT_ALLOWED |
A script runs in a Docker container on a Lambda runner group. Set its runtime to local. |
| 400 | VALIDATION_FAILED |
Also when a connection the definition names doesn’t exist, belongs to another client, or is the wrong type for its step. |
| 403 | PLAN_LIMIT |
On hosted runners: the schedule is more frequent than your plan allows, or you are at your plan’s number of hosted monitors. |
Webhooks
Section titled “Webhooks”A webhook trigger is a URL that starts a run of its monitor, for example from a deploy pipeline. See Trigger a monitor from a webhook.
| Method | Path | What it does |
|---|---|---|
| GET | /monitors/{id}/triggers |
The monitor’s webhook triggers. |
| POST | /monitors/{id}/triggers |
Creates one. Body { "name", "enabled": true, "inputs": {} }. Answers with the url and a token (pwt_…), shown once. |
| PATCH | /monitors/{id}/triggers/{triggerId} |
Changes name, enabled or inputs. |
| POST | /monitors/{id}/triggers/{triggerId}/token |
Makes a new token. The old one stops working. The new one is shown once. |
| DELETE | /monitors/{id}/triggers/{triggerId} |
Deletes a trigger. |
| POST | /hooks/{triggerId} |
Calls the trigger. No user sign-in: authenticated by the trigger’s token. Answers 202. |
A monitor can have at most 10 webhook triggers (400 TOO_MANY_TRIGGERS).
Calling POST /hooks/{triggerId}:
- Send the token as
Authorization: Bearer pwt_…, or asX-SREInsights-Token: pwt_…when the sender can’t setAuthorization. - The JSON body, up to 64 KB, reaches the check as
trigger.body. - Parameter values come from the trigger’s
inputs, overridden by the body’sparamsobject. A sender that can’t nest may send them as top-level fields named like the parameters. - One run per monitor at a time. If a run is already queued or running, the answer is
{ "queued": false, "reason": "…" }. Otherwise it is{ "queued": true, "jobId", "params" }.
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED |
A parameter value is missing or invalid. details names it under params. |
| 401 | TRIGGER_UNAUTHORIZED |
The token is missing or wrong, or the trigger or its monitor was deleted. |
| 409 | TRIGGER_DISABLED |
The trigger is turned off. |
| 409 | MONITOR_PAUSED |
The monitor is paused. |
| 413 | TRIGGER_BODY_TOO_LARGE |
The body is larger than 64 KB. |
Alert rules decide when a monitor’s results raise an alert. Field reference: Alert rules.
| Method | Path | What it does |
|---|---|---|
| GET | /monitors/{id}/rules |
The monitor’s rules, each with its last evaluation. |
| POST | /monitors/{id}/rules |
Creates a rule. |
| POST | /monitors/{id}/rules/preview |
Tries a condition against the monitor’s last 3,000 results, without saving. |
| PATCH | /alert-rules/{id} |
Changes a rule. |
| DELETE | /alert-rules/{id} |
Deletes a rule. |
POST /monitors/{id}/rules body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
name |
string | Yes | Up to 120 characters. | |
enabled |
boolean | No | true |
|
severity |
string | Yes | See Severity tiers. | |
condition |
object | Yes | When the rule matches. | |
resolveAfter |
integer, 1–20 | No | 2 |
Evaluations in a row that must not match before the alert resolves. |
reopenWindowSeconds |
integer, 0–86400 | No | 1800 |
An alert that fires again within this time reopens instead of starting over. |
labels |
object | No | {} |
Copied onto the alert. |
annotations |
object | No | summary, description, runbook_url. |
The preview body is { "condition", "resolveAfter" }. A condition whose expression doesn’t parse answers 400 INVALID_EXPRESSION, with the field’s path in details.
Alerts
Section titled “Alerts”| Method | Path | What it does |
|---|---|---|
| GET | /alerts |
Alerts, filtered by the query below. |
| GET | /alerts/{id} |
One alert with its events and notification deliveries. |
| POST | /alerts/{id}/acknowledge |
Acknowledges a firing alert. Body { "note"? }. |
| POST | /alerts/{id}/resolve |
Resolves an open alert. Body { "note"? }. |
GET /alerts query:
| Parameter | Values | Default |
|---|---|---|
state |
open, resolved, all |
open (firing or acknowledged) |
severity |
a severity | |
monitorId |
uuid | |
clientId |
uuid, or none for the organization’s own |
|
limit |
1–200 | 50 |
A note is up to 1,000 characters.
| Status | Code | When |
|---|---|---|
| 409 | ALERT_NOT_FIRING |
Only a firing alert can be acknowledged. |
| 409 | ALERT_RESOLVED |
The alert is already resolved. |
Silences
Section titled “Silences”A silence holds back notifications for matching alerts for a while. See Silences.
| Method | Path | What it does |
|---|---|---|
| GET | /silences |
Silences. ?state=current (default: active or upcoming), active, upcoming, expired or all. |
| POST | /silences |
Creates a silence. |
| POST | /silences/{id}/expire |
Ends a silence now. |
POST /silences body:
| Field | Type | Required | What it does |
|---|---|---|---|
matchers |
object | Yes | Any of severity, source, monitorIds, clientIds, labels. At least one. |
startsAt |
ISO date-time with offset | No | Defaults to now. |
endsAt |
ISO date-time with offset | One of these two | When it ends. |
durationMinutes |
integer | One of these two | How long it lasts. |
comment |
string | Yes | Why. Up to 1,000 characters. |
A silence lasts at most 30 days. One that ends before it starts, or is already over, answers 400 INVALID_SILENCE.
Notifications
Section titled “Notifications”Channels say where a notice goes. The policy is the ordered list of routes that decides which channels get which alerts. See Notifications.
| Method | Path | What it does |
|---|---|---|
| GET | /notification-channels |
Channels. |
| POST | /notification-channels |
Creates a channel. Body { "name", "connectionId", "params": {}, "enabled": true }. |
| PATCH | /notification-channels/{id} |
Changes name, enabled, or params (replaced as a whole). |
| DELETE | /notification-channels/{id} |
Deletes a channel. Routes that name it stop delivering to it. |
| GET | /notification-policy |
The routes, with version and updatedAt. |
| PUT | /notification-policy |
Replaces the whole list of routes. |
PUT /notification-policy body:
{ "routes": [ { "name": "Critical to on-call", "match": { "severity": ["critical"] }, "channels": ["<channel id>"], "continue": true }, { "name": "Everything else", "match": {}, "channels": ["<channel id>"] } ]}Up to 100 routes, each with up to 20 channels. match takes severity, source, monitorIds, clientIds and labels. An empty match matches every alert.
| Status | Code | When |
|---|---|---|
| 400 | UNKNOWN_CONNECTION |
The channel’s connection doesn’t exist. |
| 400 | NOT_A_NOTIFICATION_INTEGRATION |
The connection’s type can’t send notifications. |
| 400 | UNKNOWN_CHANNEL |
A route names a channel that doesn’t exist. details lists each one. |
Connections and integrations
Section titled “Connections and integrations”A connection holds the settings and secrets for one system SREInsights talks to. See Connections and secrets and Connection types.
| Method | Path | What it does |
|---|---|---|
| GET | /integrations |
The catalog: every connection type and what its form asks for. Needs a session, not an active organization. |
| GET | /connections |
Connections. |
| POST | /connections |
Creates a connection. |
| GET | /connections/{id} |
One connection. |
| PATCH | /connections/{id} |
Changes a connection. |
| POST | /connections/{id}/ingest-token |
A new ingest token for a push source. The old one stops working. Shown once. |
| DELETE | /connections/{id} |
Deletes a connection and its secrets. |
POST /connections body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
type |
string | Yes | A type from GET /integrations. |
|
name |
string | Yes | Up to 100 characters. | |
description |
string | No | Up to 500 characters. | |
clientId |
uuid | No | The client it belongs to. Leave out to share it across the organization. | |
runnerGroupId |
uuid | No | ||
secretMode |
sreinsights or runner |
No | sreinsights |
runner: secrets never reach SREInsights; runners read them from SREINSIGHTS_SECRET_* variables. |
config |
object | No | {} |
The type’s fields, secrets included. |
Secrets never come back: the response’s secrets says only which are set. With secretMode: "runner", runnerVariables names the variable to set on each runner. A push source’s response has ingest.url, and its ingestToken (pit_…) once, on create.
In a PATCH, leaving a secret out keeps it; setting it to null removes it.
| Status | Code | When |
|---|---|---|
| 400 | UNKNOWN_INTEGRATION |
No connection type with that name. |
| 400 | SECRET_MODE_UNSUPPORTED |
This type is used by SREInsights itself (notifications, push sources), so its secrets can’t stay on runners. |
| 400 | SECRET_REQUIRED |
A required secret was set to empty. |
| 400 | UNKNOWN_CLIENT, UNKNOWN_RUNNER_GROUP |
The client or runner group is not in this organization. |
| 400 | NOT_A_PUSH_SOURCE |
Only push sources have an ingest token. |
| 409 | CONNECTION_IN_USE |
Moving the connection to another client would break monitors or jobs that use it. |
Ingest
Section titled “Ingest”Push sources send their alerts to SREInsights. See Receive alerts from other tools.
| Method | Path | What it does |
|---|---|---|
| POST | /ingest/{type}/{connectionId} |
No user sign-in: authenticated by the connection’s ingest token. Answers 202 with { "received", "alerts" }. |
type is kibana, dynatrace or alertmanager, and must match the connection’s type. Send the token as Authorization: Bearer pit_…. Copy the full URL from the connection.
| Status | Code | When |
|---|---|---|
| 400 | INGEST_PAYLOAD_INVALID |
The body isn’t what this source sends. |
| 401 | INGEST_UNAUTHORIZED |
The token is missing or wrong, or no such connection of that type. |
Jobs and job types
Section titled “Jobs and job types”Data jobs collect data on a schedule with a built-in job type. See Jobs, Job types and Sync spec.
| Method | Path | What it does |
|---|---|---|
| GET | /job-types |
Every job type with its parameters, connection roles, default schedule and timeout. |
| GET | /jobs |
Jobs. |
| POST | /jobs |
Creates a job. |
| GET | /jobs/{id} |
One job. |
| PATCH | /jobs/{id} |
Changes a job. type can’t change. |
| DELETE | /jobs/{id} |
Deletes a job. |
| POST | /jobs/{id}/run |
Run now, with the job’s parameters overridden by params. Body { "params"? }. Answers 202. |
| POST | /jobs/{id}/backfill |
One run for a range of days. Body { "start", "end", "params"? }, dates as YYYY-MM-DD, both included. Answers 202. |
| POST | /jobs/{id}/preview |
Queues a dry run of a sync. Answers 202 with { "taskId", "state": "queued", "version", "queueExpiresAt" }. |
| GET | /jobs/{id}/previews/{taskId} |
A preview’s state: queued, running, done (with what it found) or failed (with error). |
| GET | /jobs/{id}/runs |
Runs, newest first. Takes limit and before. |
POST /jobs body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
name |
string | Yes | Up to 120 characters. | |
description |
string | No | ||
clientId |
uuid or null |
No | The client it belongs to. null for the organization’s own. |
|
enabled |
boolean | No | true |
A sync must be created paused. |
type |
string | Yes | A name from GET /job-types. |
|
params |
object | No | {} |
The type’s parameters. |
connections |
object | No | {} |
Up to 10 role: connection id pairs. |
runsOn |
object | Yes | { "group", "labels": [] }, as for monitors. |
|
schedule |
object | Yes | { "cron", "timezone": "UTC" }. |
|
timeoutMs |
integer, 10000–900000 | No | The type’s default | |
alerting |
object | No | { "onFailure": true, "freshnessHours": null, "severity": "high" }. |
|
sync |
object | For type sync |
The sync’s spec. |
PATCH /jobs/{id} also takes typeVersion, to move the job to another version of its type. It rejects fields it doesn’t know.
Run now and Backfill answer { "runId", "status": "queued", "queueExpiresAt", "params", "window" }.
| Status | Code | When |
|---|---|---|
| 400 | UNKNOWN_JOB_TYPE |
No job type with that name, or the job’s version is no longer known. |
| 400 | BACKFILL_NOT_SUPPORTED |
The type collects from where it left off, so it has no day range. |
| 400 | NOT_A_SYNC |
Only a sync has a preview. |
| 400 | RUNNER_CREDENTIALS_NOT_HOSTED |
The type uses its runner’s own credentials, and the job runs on a hosted location. |
| 400 | HOSTED_RUNNER_LOCAL_SECRETS |
A connection keeps its secrets on your runners, and the job runs on a hosted location. |
| 400 | INVALID_SCHEDULE, SCHEDULE_TOO_FREQUENT, UNKNOWN_RUNNER_GROUP, UNKNOWN_CLIENT |
As for monitors. |
| 400 | VALIDATION_FAILED |
Also for a backfill range in the future or longer than the type allows in one run. |
| 403 | PLAN_LIMIT |
On hosted runners: the schedule is more frequent than your plan allows, or you are at your plan’s number of hosted jobs. |
| 409 | JOB_RUN_ACTIVE |
A run of this job is already waiting or running. A job runs one at a time. |
| 409 | SYNC_NOT_PREVIEWED |
The sync’s current version hasn’t been previewed. Save it paused, preview it, then switch it on or run it. |
Clients
Section titled “Clients”Clients group monitors, jobs, connections and status pages inside one organization. See Clients.
| Method | Path | What it does |
|---|---|---|
| GET | /clients |
Clients. |
| POST | /clients |
Creates a client. Body { "name" }. |
| PATCH | /clients/{id} |
Renames a client. Body { "name" }. |
| DELETE | /clients/{id} |
Deletes a client that nothing belongs to any more. |
| Status | Code | When |
|---|---|---|
| 409 | CLIENT_NAME_TAKEN |
A client with this name exists. |
| 409 | CLIENT_IN_USE |
Records or members still belong to the client. Move or delete them first. |
Status pages
Section titled “Status pages”See Status pages and Share a status page.
| Method | Path | What it does |
|---|---|---|
| GET | /status-pages |
Status pages. ?clientId=<id> for one client’s, ?clientId=none for the organization’s own. |
| POST | /status-pages |
Creates a page. |
| GET | /status-pages/{id} |
One page. |
| GET | /status-pages/{id}/summary |
Uptime, per-monitor rates and certificates. ?window=day, week (default) or month. |
| PATCH | /status-pages/{id} |
Changes a page. |
| PUT | /status-pages/{id}/visibility |
Owners and Admins only. Body { "visibility": "private" | "link" }. |
| DELETE | /status-pages/{id} |
Deletes a page. |
| GET | /public/status/{token} |
Public, no sign-in. A page shared by link. |
POST /status-pages body: name, description, clientId (null for the organization’s own), and items, up to 50:
{ "name": "Acme services", "items": [ { "monitorId": "<monitor id>", "label": "Checkout" }, { "monitorId": "<monitor id>", "kind": "certificate" }, { "kind": "job", "jobId": "<job id>", "label": "Nightly import" } ]}A monitor item’s kind is monitor (default) or certificate (only its TLS certificate).
Setting visibility to link makes a new share token each time. Owners and Admins see it as shareToken; the page’s address is <your SREInsights URL>/s/<token>. Setting it back to private turns the old address off.
GET /public/status/{token} answers a plain-text 404 for a wrong or turned-off token. Answers may be cached for 60 seconds, carry x-robots-tag: noindex, nofollow, and are rate limited (see Rate limits).
| Status | Code | When |
|---|---|---|
| 400 | UNKNOWN_MONITOR, UNKNOWN_JOB |
An item names a monitor or job that doesn’t exist. |
| 400 | ITEM_OF_ANOTHER_CLIENT |
A client’s page lists another client’s monitor or job. |
| 400 | UNKNOWN_CLIENT |
clientId is not in this organization. |
| 403 | POLICY_DENIED |
Changing visibility without the Owner or Admin role. |
Reports
Section titled “Reports”Scheduled summaries of monitors, sent to notification channels. See Reports.
| Method | Path | What it does |
|---|---|---|
| GET | /reports |
Reports. |
| POST | /reports |
Creates a report. |
| GET | /reports/{id} |
One report. |
| GET | /reports/{id}/runs |
The report’s past sends. |
| PATCH | /reports/{id} |
Changes a report. |
| POST | /reports/{id}/send |
Sends it now. Answers 202. |
| DELETE | /reports/{id} |
Deletes a report. |
POST /reports body:
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
name |
string | Yes | Up to 120 characters. | |
description |
string | No | ||
enabled |
boolean | No | true |
|
cron |
string | Yes | When to send. | |
timezone |
string | No | UTC |
|
monitorIds |
uuid[] | No | [] |
Up to 100. |
channelIds |
uuid[] | Yes | 1–20 notification channels. | |
format |
summary or detailed |
No | summary |
|
includeRuns |
boolean | No | true |
Count every run since the last report, not only the latest result. |
Sending a report with no channels answers 400 REPORT_HAS_NO_CHANNELS.
Deployments
Section titled “Deployments”A deployment is a planned change with its checklist, approvals and tickets. See Deployments.
| Method | Path | What it does |
|---|---|---|
| GET | /deployments |
Deployments. Filter with ?status= and ?environment=. |
| POST | /deployments |
Creates a deployment. |
| GET | /deployments/{id} |
One deployment. |
| PATCH | /deployments/{id} |
Changes a deployment. checklist, approvals and tickets are replaced as a whole. |
| POST | /deployments/{id}/duplicate |
Copies a deployment. Answers 201. |
| DELETE | /deployments/{id} |
Deletes a deployment. |
| Field | Type | Default | What it does |
|---|---|---|---|
name |
string, required | Up to 160 characters. | |
description |
string | Up to 4,000 characters. | |
environment |
development, staging, production |
production |
|
status |
draft, pending_approval, approved, in_progress, completed, failed |
draft |
|
scheduledAt |
ISO date-time or null |
||
checklist |
array, up to 100 | [] |
Items with title, description, done, doneAt, doneBy, ticket, approvals. |
approvals |
array, up to 50 | [] |
{ "name", "email", "status": "pending" | "approved" | "rejected", "comment", "respondedAt" }. |
tickets |
array, up to 50 | [] |
{ "key", "title", "url" }, for example JIRA-123. |
ADAM, the AI assistant. See ADAM. The operator must give the instance an AI API key; until then, /ai/flows, /ai/analyze, /ai/scripts, /ai/tests and /ai/fix answer 503 AI_DISABLED.
| Method | Path | What it does |
|---|---|---|
| GET | /ai/status |
{ "enabled", "model" }. |
| POST | /ai/flows |
A flow from a description. Body { "prompt", "current"? }. |
| POST | /ai/analyze |
Reads a ticket or incident text: entities, errors and suggested checks. Body { "text" }. |
| POST | /ai/scripts |
Code for a script step. Body { "prompt", "language": "node" | "python" | "shell", "current"?, "runtime"?, "inFlow"?, "stepIds"?, "envVars"? }. |
| POST | /ai/tests |
A monitor as test code. Body { "name", "description"?, "definition", "parameters"?, "framework": "playwright" | "pytest" | "k6" | "postman" }. |
| POST | /ai/fix |
A patch for pasted code. Body { "incident", "code", "filename"?, "language"? }. |
| POST | /ai/code/fetch |
Asks one of your runners for excerpts of the files an incident names. Body { "connectionId", "groupId", "repository"?, "ref"?, "text"? or "hints"? }. Answers 202 with { "taskId", "hints" }. |
| GET | /ai/code/tasks/{id} |
A code task’s state: queued, running, done or failed. |
| Status | Code | When |
|---|---|---|
| 422 | AI_REFUSED |
The AI declined the request. |
| 422 | NO_CODE_HINTS |
No file names found in the text. Add hints by hand. |
| 422 | NOT_A_CODE_HOST |
The connection is not GitHub or GitLab. |
| 422 | HOSTED_GROUP_NOT_ALLOWED |
Find the code runs only on your own runner groups. |
| 422 | BAD_REPOSITORY |
Name the repository as owner/repo (GitHub) or group/project (GitLab). |
| 429 | AI_RATE_LIMITED |
The AI service is limiting requests. Try again in a minute. |
| 502 | AI_AUTH_FAILED, AI_UNREACHABLE, AI_FAILED, AI_UNPARSEABLE |
The AI service rejected the key, couldn’t be reached, failed, or gave an answer that couldn’t be read. |
| 503 | AI_DISABLED |
ADAM is off on this instance. |
Stores
Section titled “Stores”Connect Etsy and eBay stores by signing in to them. Available only where the operator set it up. See Stores.
| Method | Path | What it does |
|---|---|---|
| GET | /stores |
The providers (with whether each is on) and the connected stores. |
| POST | /stores/connect |
Starts a sign-in. Body { "provider": "etsy" | "ebay", "storeKey", "clientId"?, "label"? }. Answers 201 with { "authorizeUrl", "expiresAt" }. |
| POST | /stores/callback |
Finishes a sign-in with what the provider sent back. Body { "provider", "state", "code"?, "error"?, "errorDescription"? }. |
| DELETE | /stores/{id} |
Forgets the store in SREInsights. Its stored token and the provider’s approval stay. |
Open authorizeUrl in the browser of the person who started the sign-in. It works for ten minutes. storeKey is lower-case letters, digits and single hyphens.
| Status | Code | When |
|---|---|---|
| 400 | STATE_EXPIRED |
The sign-in took more than ten minutes. Start again. |
| 400 | STATE_UNKNOWN |
The sign-in is unknown or was for another provider. Start again. |
| 404 | STORE_CONNECT_OFF |
Connecting stores isn’t set up for this organization on this instance. |
| 409 | STORE_OWNED_ELSEWHERE |
The store is connected in another organization on this instance. |
| 409 | STORE_LOCKED |
The store’s token is being refreshed right now. Wait a minute and try again. |
| 409 | STORE_UNKNOWN |
The store isn’t known to the instance, or was removed while you signed in. |
Insights
Section titled “Insights”| Method | Path | What it does |
|---|---|---|
| GET | /insights/overview |
Runs per day and this month’s totals, for the Overview page. ?days= 1–31, default 7. |
Health checks
Section titled “Health checks”Two endpoints sit outside /api/v1 and need no sign-in:
| Method | Path | What it does |
|---|---|---|
| GET | /healthz |
{ "status": "ok" } while the server process runs. |
| GET | /readyz |
{ "status": "ready" } when the database is reachable, otherwise 503. |
Examples
Section titled “Examples”Set these once:
export SRI=https://console.sreinsights.com/api/v1Sign in
Section titled “Sign in”curl -s -c cookies.txt -X POST "$SRI/auth/login" \ -H 'content-type: application/json' \ -d '{"email": "you@example.com", "password": "your password"}'{ "status": "success", "data": { "accessToken": "eyJhbGciOiJIUzI1NiIs…" } }Keep the access token, and the cookie file for refreshing:
export TOKEN=eyJhbGciOiJIUzI1NiIs…curl -s -b cookies.txt -c cookies.txt -X POST "$SRI/auth/refresh"List monitors
Section titled “List monitors”curl -s "$SRI/monitors" -H "authorization: Bearer $TOKEN"{ "status": "success", "data": [ { "id": "0193a1c2-…", "name": "Checkout API", "enabled": true, "runsOn": { "groupId": "0193…", "group": "eu-prod", "hosted": false, "labels": [] }, "schedule": { "cron": "*/5 * * * *", "timezone": "UTC", "inputs": {}, "nextRunAt": "2026-11-22T10:05:00.000Z", "lastRunAt": "2026-11-22T10:00:00.000Z" }, "lastStatus": "ok", "activeRun": null } ]}Run a monitor now with parameters
Section titled “Run a monitor now with parameters”curl -s -X POST "$SRI/monitors/0193a1c2-…/run" \ -H "authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"params": {"region": "eu"}}'{ "status": "success", "data": { "jobId": "0193b7d0-…", "status": "queued", "queueExpiresAt": "2026-11-22T10:08:12.000Z", "params": { "region": "eu" } }}Watch for its result with GET /monitors/{id}/results?limit=1.
Trigger a webhook
Section titled “Trigger a webhook”Use the URL and token you got when you created the trigger:
curl -s -X POST "https://console.sreinsights.com/api/v1/hooks/0193c4e1-…" \ -H "authorization: Bearer pwt_…" \ -H 'content-type: application/json' \ -d '{"params": {"version": "2.4.1"}, "commit": "a1b2c3d"}'{ "status": "success", "data": { "queued": true, "jobId": "0193c4f0-…", "params": { "version": "2.4.1" } } }The whole body, commit included, is available to the check as trigger.body.