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:
- 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. - Include the token in the
Authorizationheader of every request:
Authorization: Bearer <your-access-token>- 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
| Convention | Details |
|---|---|
| Content-Type | application/json for all request and response bodies |
| Field naming | camelCase (e.g., slxName, createdAt, runSession) |
| Timestamps | ISO 8601 with timezone (e.g., 2026-03-01T12:00:00Z) |
| Identifiers | Integer primary keys |
| Pagination | List responses use a standard envelope: { count, next, previous, results } |
| Page navigation | Use the page query parameter (some endpoints also support page-size) |
Status Codes
| Code | Meaning |
|---|---|
200 OK | Request succeeded |
201 Created | Resource created successfully |
204 No Content | Resource deleted successfully |
400 Bad Request | Invalid request body or parameters |
401 Unauthorized | Missing or invalid authentication token |
403 Forbidden | Insufficient permissions for the requested resource |
404 Not Found | Resource does not exist |
429 Too Many Requests | Rate limit exceeded — implement exponential backoff |
500 Internal Server Error | Server-side error |
API Reference
Detailed endpoint documentation is organized by resource. Select a topic below to view available operations, parameters, and example responses.
| Resource | Description |
|---|---|
| Workspaces | Retrieve and manage workspaces, configuration uploads, health, and status |
| SLXs, SLIs, SLOs & Runbooks | Query observability primitives — expectations, indicators, objectives, and runbook definitions |
| Run Sessions & Run Requests | Create diagnostic sessions, execute runbook tasks, and track execution status |
| Issues | View, update, and analyze detected issues with AI-powered JIT summaries |
| Workflows & Personas | Manage automation workflows, trigger execution, and configure AI personas |
| CodeCollections & Codebundles | Browse code repositories, branches, codebundle metadata, and statistics |
| Users | User profiles, search, activity feeds, and workspace membership |
| Task Search & Activities | Semantic task search and workspace activity tracking |