LogoLogo
Reliability HubAPI DocsPlatform
  • Welcome to Steadybit
  • Quick Start
    • First Steps
    • Compatibility
    • Install Agent and Extensions
    • Run an Experiment
    • Deploy Example Application
  • Concepts
    • Actions
    • Discovery
    • Query Language
  • Install and Configure
    • Install Agent
      • Architecture
      • Install on Kubernetes
      • Install on Linux Hosts
      • Install using Docker Compose
      • Install on Amazon ECS
      • Extension Registration
      • Using Mutual TLS for Extensions
      • Configuration Options
      • Agent State
      • Agent API
    • Install On-Prem Platform
      • Install on Minikube
      • Advanced Agent Authentication
      • Configuration Options
      • Maintenance & Incident Support
      • Syncing Teams via OIDC Attribute
    • Manage Environments
    • Manage Teams and Users
      • Users
      • Teams
      • Permissions
    • Manage Experiment Templates
  • Use Steadybit
    • Experiments
      • Design
      • Run
      • Run History
      • Schedule
      • Variables
      • Emergency Stop
      • Share
        • Templates
        • Duplicate
        • File
      • OpenTelemetry Integration
    • Explorer
      • Landscape
      • Targets
      • Advice
    • Reporting
  • Integrate with Steadybit
    • Extensions
      • Anatomy of an Extension
      • Extension Installation
      • Extension Kits
      • Available Extensions
    • API
      • Interactive API Documentation
    • CLI
    • Badges
    • Webhooks
      • Custom Webhooks
      • Preflight Webhooks
    • Preflight Actions
    • Slack Notifications
    • Audit Log
    • Hubs
  • Troubleshooting
    • How to troubleshoot
    • Common fixes
      • Extensions
      • Agents
      • On-prem platform
Powered by GitBook

Extension Docs

  • ActionKit
  • DiscoveryKit
  • EventKit

More Resources

  • Reliability Hub
  • API Docs
On this page
  • Access Tokens
  • Create a new Access Token
  • OpenApi Specification
  • Requests and Responses
  • Example: Create Experiment
  • Example: Run Experiment
  • Create a golang client with oapi-codegen

Was this helpful?

Edit on GitHub
  1. Integrate with Steadybit

API

Last updated 3 months ago

Was this helpful?

The Steadybit Web API allows interfacing with the platform. We follow the principle that every feature available at UI also is available via API.

In order to access the API, you need to have an Access token.

Access Tokens

In order to use the API you need to create an API access token and provide it via the Authorization header in your API requests.

API access tokens are managed by the administrator and team owners, and can be found in Settings → API Access Tokens section in the UI.

We differentiate between team tokens and admin tokens.

Team Tokens are bound to a team and can be used to access all experiments of a team.

Admin Tokens have access to management APIs to manage e.g. teams or environments. Admin tokens are only available to the administrator user.

Create a new Access Token

You can create a new access token via the platform's user interface. Go to Settings → API Access Tokens.

Once you created a new API access token, you can't see it again. Make sure to save it at a safe place!

Create an Admin Token via internal API

On-Prem customers have also the possibility to create an admin token via internal APIs.

Create Admin Token via CLI

To generate a new admin token in your On-Prem Platform via CLI, first ssh into the platform server. Afterward, run the following command:

/scripts/createAdminToken.sh

Missing mandatory arguments
Usage: /scripts/createAdminToken.sh -n <name> -t <tenantKey>
  -n | --name <name>           Name of the token
  -t | --tenantKey <tenantKey> Tenant key
  -h | --help                  Show this help
  
  
/scripts/createAdminToken.sh -t demo -n AdminToken
Z8pChlF2*************

The token will be printed to the console.

[On-Prem] Create Admin Token via HTTP API

To generate a new admin token in your On-Prem Platform via HTTP API, first ssh into the platform server. Afterward, you can run curl:

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name":"'$NAME'","tenantKey":"'$TENANTKEY'"}' \
  http://localhost:9090/actuator/adminaccesstoken

This end point is only accessible for On-Prem customers and only from localhost. It can not be accessed from outside your server.

OpenApi Specification

Requests and Responses

All API requests require a specified access token via the Authorization header in the format Authorization: accessToken <token>.

If applicable, request and response bodies are expressed using json or yml, depending on the used Content-Type and Accept headers. Success or failure of an API call is expressed via HTTP status.

Too Many Requests

API endpoints are rate limited and may return the HTTP status code 429 - Too Many Requests.

curl \
 -v \
 -H "Authorization: accessToken <token>"\
 -H "Accept: application/json"\
 https://platform.steadybit.com/api/<endpoint>
[...]
< HTTP/1.1 429 Too Many Requests
< ratelimit-limit: 100;w=60
< ratelimit-remaining: 0
< ratelimit-reset: 46
< retry-after: 46
[...]

Example: Create Experiment

This is how you can create an experiment (json is supported as well):

curl \
  -i \
  -H 'Content-Type: application/x-yaml' \
  -H 'Authorization: accessToken <token>' \
  https://platform.steadybit.com/api/experiments \
  --data '
---
name: Experiment API Test
team: ADM
environment: Global
lanes:
  - steps:
      - !<action>
        actionType: check:http
        parameters:
          method: "GET"
          url: "https://example.com"
          headers: []
          successRate: 100
          maxConcurrent: 5
          requestsPerSecond: 1
          duration: "10s"
          followRedirects: false
          readTimeout: "5s"
          connectTimeout: "5s"
          statusCode: "200-299"
'

The Location header of the response indicates the url of the newly created experiment:

location: https://platform.steadybit.com/api/experiments/ADM-

Example: Run Experiment

You can then run the experiment:

curl \
  -i \
  -X POST \
  -H 'Authorization: accessToken <token>' \
  https://platform.steadybit.com/api/experiments/ADM-1/execute

Create a golang client with oapi-codegen

compatibility:
  circular-reference-limit: 11

Here an example configuration to generate a go client with net/http:

package: api
generate:
  std-http-server: true
  models: true
output: gen.go
compatibility:
  circular-reference-limit: 11

And then in your golang file:

//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml https://platform.steadybit.com/api/spec

We provide a as well as an . In case you are using our on-prem variant you can access it at http://<your-installation-url>/api/spec.

In this case the Retry-After response header contains the number of seconds to wait before executing further requests, see . Furthermore, the response headers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, as defined in the IETF draft , are returned containing more details.

In case you want to , you should add this parameter to your configuration file:

OpenApi 3.0 Specification for the API
interactive documentation
RFC 7231
RateLimit Header Fields for HTTP
generate the structs
Management of API Access Token
Add a new API access token