API Reference > API examples

Docs Home

API examples

No items found.

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

‍

Before running these examples, you'll need to authenticate. See Getting started with the Gremlin API.

‍

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:

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 args 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"} } }
    }'

Classes, methods, & attributes