Everything within Gremlin can be done via our API. Integrate it with your CI/CD pipeline! Explore our 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 /users/auth

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data 'email=gremlin%40gremlin.com&password=changeit' \
    'https://api.gremlin.com/v1/users/auth'

The Gremlin API issues access tokens to users on an org basis. So if a user belongs to two orgs, Gremlin will issue that user two access tokens.

[
  {
   "expires_at": "2099-01-00T00:00:00.000Z",
   "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGMzOmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAw",
   "identifier": "gremlin@gremlin.com",
   "org_id": "e7352a6b-a9a0-513c-81e4-980f680a70c3",
   "org_name": "My Org (Production)",
   "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0001",
   "role": "USER",
   "token": "5ca1ab1e-dead-beef-ffff-0000ffff0000"
  },
  {
   "expires_at": "2099-01-00T00:00:00.000Z",
   "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy",
   "identifier": "gremlin@gremlin.com",
   "org_id": "e7352a6b-a9a0-513c-81e4-980f680a70c4",
   "org_name": "My Org (Staging)",
   "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0003",
   "role": "USER",
   "token": "5ca1ab1e-dead-beef-ffff-0000ffff0002"
  },
]

Creating Attacks

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

command

The command attribute is used to tell Gremlin what attack should be run, and how it should be run.

subattributes

  • type: one of the Gremlin types
  • args: 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:

# Add 1 core of CPU load to a random host for 30 seconds
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'
no args necessary

Some attacks have no required args, and so args can be omitted.

# shutdown a random host
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "shutdown" },
        "target": { "type": "Random" }
    }'
multiple arg values

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

# Add latency to all DNS requests to DNS servers
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "latency", "args": [ "-i", "8.8.8.8", "-i", "8.8.4.4" ] },
        "target": { "type": "Random" }
    }'

target

The target attribute is used to tell Gremlin what clients should be targeted by the attack.

randomly target an active host
# Pick a host at random from all active hosts
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --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 --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Random", "tags": { "service": "api" } }
    }'
target an exact set of hosts
# Target client1 and client2
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "exact": ["client1", "client2"] }
    }'

labels

target a set of docker containers

Docker containers can be targeted with the labels property. Labels are a map of string keys and values which are used by Gremlin to find running Docker containers. For Gremlin to match a Docker container to the requested attack, all labels provided must be present on the container. The following example targets all containers that have the label service=api running on hosts client1 and client2.

# Target all docker containers that have the label "service=api" on client1 and client2
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer $token" \
    https://api.gremlin.com/v1/attacks/new \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "exact": ["client1", "client2"] },
        "labels": { "service": "api" }    
    }'