RunWhen Public API Reference

The RunWhen Platform API gives you programmatic access to your workspaces, observability data, automation workflows, and troubleshooting tools. Use it to integrate RunWhen into your existing toolchains, build custom dashboards, or automate operational tasks at scale.

Getting Started

Base URL

All API requests are made against your RunWhen instance:

https://<your-instance>.runwhen.com/api/v3/

All paths in this documentation are relative to this base URL. The current API version is v3.

Authentication

The RunWhen API authenticates requests using JSON Web Tokens (JWT). To get started:

1. Obtain a token by calling POST /api/v3/token/ with your credentials. The endpoint accepts both JSON and form-urlencoded payloads for compatibility with service accounts and CLI tools.

2. Include the token in the Authorization header of every request:

Authorization: Bearer <your-access-token>

3. Refresh transparently — access tokens are short-lived. Use the refresh token from the initial response to obtain new access tokens via POST /api/v3/token/refresh/ without re-authenticating.

For full endpoint details, see the Authentication section in the child pages below.

Core Concepts

Workspaces

A Workspace is the top-level container for all RunWhen resources. Every SLX, run session, issue, workflow, and persona belongs to a workspace. Workspaces map to a specific environment, team, or operational scope and are backed by a Git repository that stores their declarative configuration.

SLXs (Service Level Expectations)

An SLX defines what "healthy" looks like for a service or component. Each SLX can contain:

• SLI (Service Level Indicator) — the metric being measured

• SLO (Service Level Objective) — the target threshold for that metric

• Runbook — the automated remediation or diagnostic action to take when the SLO is breached

SLX identifiers use a short name format in the API (e.g., check-cpu-usage). The workspace prefix is handled automatically based on the URL path — you never need to pass the full internal name.

Run Sessions & Run Requests

A Run Session groups one or more Run Requests into a single diagnostic or remediation workflow. Sessions can be initiated by users, alerts, Slack commands, workflows, or API calls. Each Run Request represents the execution of a specific runbook task against an SLX.

Issues & Occurrences

Issues are problems or anomalies detected during run sessions. The platform tracks repeat detections as Occurrences and can generate AI-powered JIT Summaries with root cause analysis and recommended next steps.

Workflows & Personas

Workflows define event-driven or on-demand automation — triggered by alerts, webhooks, or manual invocation. Personas are AI assistants configured with domain-specific expertise, confidence thresholds, and filtering rules that determine how they respond to issues.

CodeCollections & Codebundles

CodeCollections are Git repositories containing Codebundles — reusable troubleshooting and automation scripts written in Robot Framework. They power the SLIs, SLOs, and Runbooks across the platform.

Task Search

Task Search provides semantic, vector-based search for finding the most relevant troubleshooting tasks and codebundles based on a natural language description of the problem.

Conventions

Status Codes

API Reference

Detailed endpoint documentation is organized by resource. Select a topic below to view available operations, parameters, and example responses.