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 /users/auth

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'

If you have MFA enabled, include the token in your call to /users/auth/mfa/auth

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'

If you are a member of more than one company, you can supply the company name with 'companyName=Your Company Name'.

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"
  },
]

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 command attribute is used to tell Gremlin which 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: $bearertoken" \
    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: $bearertoken" \
    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: $bearertoken" \
    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: $bearertoken" \
    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: $bearertoken" \
    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: $bearertoken" \
    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: $bearertoken" \
    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" }    
    }'