Dashboard
API Reference

Examples

Everything within Gremlin can be done via our API. Explore the Gremlin API with our Interactive API playground.

Authentication and access tokens

All API requests require an API access token provided in the Authorization Header.

Authorization: Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGMzOmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAw

You can access your tokens by providing your gremlin username and password to <span class="code-class-custom">/users/auth</span>

BASH

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=gremlin@gremlin.com' \
    --data-urlencode 'password=changeit' \
    'https://api.gremlin.com/v1/users/auth?getCompanySession=true'

If you have MFA enabled, include the token from your password authenticator in your call to <span class="code-class-custom">/users/auth/mfa/auth</span>

BASH

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=gremlin@gremlin.com' \
    --data-urlencode 'password=changeit' \
    --data-urlencode 'token=000000' \
    'https://api.gremlin.com/v1/users/auth/mfa/auth?getCompanySession=true'

If you are a member of more than one company, you can supply the company name with <span class="code-class-custom">'companyName=Your Company Name'</span>.

These calls will result in a JSON response containing information about your session and more

JSON

{
  "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
  "company_name": "My Company",
  "roles": ["COMPANY_USER"],
  "privileges": ["COMPANY_DEFAULT"],
  "expires_at": "2099-01-00T00:00:00.000Z",
  "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy",
  "identifier": "gremlin@gremlin.com",
  "teams": [
    {
      "identifier": "e7352a6b-a9a0-513c-81e4-980f680a70c4",
      "name": "My Team",
      "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
      "roles": ["TEAM_USER"],
      "privileges": ["READ_TEAM_USERS", "TEAM_DEFAULT"]
    }
  ],
  "last_login": "2098-01-00T00:00:00.000Z",
  "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0003",
  "token": "5ca1ab1e-dead-beef-ffff-0000ffff0002"
}

Note the Bearer token from the value of "header".

export bearertoken="Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy"

Creating Attacks

Note
All options from the CLI are available through the /attacks/new API, by passing them via command.args.

command

The <span class="code-class-custom">command</span> attribute is used to tell Gremlin which attack should be run, and how it should be run.

subattributes

  • <span class="code-class-custom">type</span>: one of the Gremlin types
  • <span class="code-class-custom">args</span>: the arguments for the gremlin, identical to those passed via the CLi and UI.
short and long flags

Both the short and long form of arg flags are acceptable:

BASH

# Add 1 core of CPU load to a random host for 30 seconds
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'

no args necessary

Some attacks have no required args so <span class="code-class-custom">args</span> can be omitted.

BASH

# shutdown a random host
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "shutdown" },
        "target": { "type": "Random" }
    }'

multiple arg values

Some arguments can take multiple values, they can be specified like this:

BASH

# Pick a host at random from all active hosts
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Random" }
    }'

# Pick a host at random from all active hosts with the tage service=api
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Random", "tags": { "service": "api" } }
    }'

target an exact set of hosts
BASH

# Target identifier1 and identifier2
curl -x POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "hosts" : { "ids": ["identifier1","identifier2"] } }
    }'

targeting a container
BASH

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "containers":{"ids":["2d9ddc7a4284cd23d2d2bc21e11af021a84ee5c7536073c5a5d6888adf1f290c"]}}
    }'


target a set of docker containers
BASH

# Target 2 docker containers that have the label "service=api"
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target":{ "type": "Random", "exact": 2, "containers": {"labels": {"service":"api"} } }
    }'


No items found.
Previous
This is some text inside of a div block.
Compatibility
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Integrations
Health Checks
Notifications
Command Line Interface
Updating Gremlin
Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Targets
Experiments
Scenarios
GameDays
Overview
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Examples
Container security
General
Linux
Windows
Chao
Helm
Glossary
Alfi
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Application Level Fault Injection (ALFI)
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Jira
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Overview
Overview
Overview
Overview
Overview
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Role Based Access Control
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Slack
Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Users
Webhooks
Integration Agent for Linux
Test Suites
Restricting Testing Times
Reports
Process Exhaustion Experiment
Enabling DNS collection