canonical: https://jentic.com/apis/gremlin.com/gremlin

# Gremlin API

Gremlin is a chaos engineering platform that injects controlled failure into systems so teams can verify resilience before production incidents do. The API exposes attacks, scenarios, status checks, clients/targets, teams, and schedules - letting agents launch and stop chaos experiments, schedule recurring runs, and pull attack reports programmatically.

## For AI agents

Launch, schedule, and halt Gremlin chaos engineering attacks and scenarios programmatically, and pull reports on attack history.

## Scope

Does not handle observability metrics, on-call paging, or root-cause analysis - use for chaos attack and scenario orchestration only.

## Capabilities

- Launch a single chaos attack against a targeted host or container with POST /attacks
- Halt all currently active attacks via DELETE `/attacks/active`
- Run multi-step chaos scenarios with POST `/scenarios/{scenarioId}/runs`
- Schedule recurring chaos runs with /schedules endpoints
- List Gremlin clients (agents) reporting in via /clients
- Generate aggregated attack reports with GET `/reports/attacks`
- List teams and inspect team membership through `/orgs/teams`

## Use cases

### Production Resilience Game Day

Run a coordinated chaos experiment as part of a game day. The team uses POST `/scenarios/{scenarioId}/runs` to kick off a scripted scenario, GET `/scenarios/{scenarioId}/runs` to monitor progress, and DELETE `/attacks/active` as a kill switch if customer impact rises. Game days catch latent failure modes that staging never reveals.

Example prompt: Trigger POST `/scenarios/{scenarioId}/runs` with a known scenario ID, poll GET `/scenarios/{scenarioId}/runs` every 30 seconds, and call DELETE `/attacks/active` if a SLO alert fires.

### Scheduled Chaos in CI/CD

Run a small chaos attack as part of a release validation pipeline. After deploying to staging, the pipeline calls POST /attacks to inject latency or CPU pressure on the new version and then DELETE `/attacks/{attackGuid}` once verification completes. This catches resource sizing regressions before they reach production.

Example prompt: Call POST /attacks with a 5-minute latency attack on the staging service, wait for completion, then call DELETE `/attacks/{attackGuid}` and pull GET `/reports/attacks` to attach to the release.

### Recurring Resilience Drills

Schedule chaos runs on a recurring cadence to keep teams sharp and uncover drift. The /schedules endpoints let SREs configure weekly or daily runs of approved scenarios. Combined with `/reports/attacks` the platform produces a measurable resilience posture over time.

Example prompt: Call POST /schedules to create a weekly schedule for a known scenarioId, then verify it appears in GET /schedules.

### AI Agent Incident Drill Coordinator

An on-call SRE assistant uses Jentic to launch sanctioned chaos experiments on demand - the human says 'run the latency drill on the search service' and the agent searches Jentic, loads the right Gremlin operation, and executes it under the team's API key without hard-coding URLs.

Example prompt: Search Jentic for 'run a chaos scenario', load the POST `/scenarios/{scenarioId}/runs` schema, execute with the named scenarioId, and report the run ID back to the on-call channel.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/attacks` | Launch a chaos attack |
| DELETE | `/attacks/active` | Halt all active attacks |
| GET | `/scenarios` | List chaos scenarios |
| POST | `/scenarios/{scenarioId}/runs` | Run a scenario |
| POST | `/schedules` | Create a recurring chaos schedule |
| GET | `/clients` | List Gremlin agent clients |
| GET | `/reports/attacks` | Aggregated attack history |
| GET | `/status` | Service status check |

## Key resources

- **attacks** — Launch, list, halt, and inspect single chaos attacks
- **scenarios** — Manage and execute multi-step chaos scenarios and their runs
- **schedules** — Schedule recurring chaos runs
- **clients** — List Gremlin agent clients and their hosts/containers
- **orgs/teams** — Manage teams and team membership
- **reports/attacks** — Aggregated attack history reports

## Why Jentic

- **Setup:** Wiring the Gremlin API by hand means carrying its bearer token alongside the X-Gremlin-Team-Id header and mapping the attack, scenario, client, and schedule endpoints yourself. Through Jentic you install once, import the Gremlin API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Gremlin puts the scenario and attack ids in the URL path (`/scenarios/{scenarioId}`, `/attacks/{attackGuid}`), so a rule can pin your agent to one scenario: it can read that scenario and its runs and nothing else. You choose the operations it may call, so ones like launching or halting an attack are not included unless you add them.
- **Credential handling:** Your Gremlin credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list active attacks' or 'read a chaos scenario's runs', and Jentic returns the matching Gremlin operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PagerDuty API** — Incident response platform - link Gremlin attacks to PagerDuty alerts to verify on-call paging works end-to-end.
- **New Relic API** — Observability platform to measure the impact of a Gremlin attack on real metrics.
- **Stripe API** — Used as the canary in many fintech chaos experiments - Gremlin injects failure, Stripe transactions verify recovery.

## FAQ

### What authentication does the Gremlin API use?

Gremlin uses an HTTP bearer token (the Gremlin API key) and additionally requires the X-Gremlin-Team-Id header to scope calls to a team. Jentic stores both values encrypted in your Jentic One instance and injects them at call time, so the bearer key never enters the agent's context.

### Can I halt all running chaos attacks with one call?

Yes. DELETE `/attacks/active` stops every active attack across the team - useful as a kill switch in an incident. Pair it with a SLO-driven trigger so the agent halts attacks the moment customer impact appears.

### What are the rate limits for the Gremlin API?

The OpenAPI spec does not publish explicit rate limits. Gremlin enforces fair-use limits at the platform level. Production workflows should handle 429 responses with exponential backoff and surface failures to the on-call channel.

### How do I run a chaos scenario through Jentic?

Search Jentic for 'run a chaos scenario', load the POST `/scenarios/{scenarioId}/runs` schema, then execute with the scenario ID. The bearer key and team ID are injected from the vault, so the agent only supplies the scenario parameters.

### Does the Gremlin API support scheduling recurring attacks?

Yes. POST /schedules creates a recurring schedule, GET /schedules lists existing schedules, and DELETE `/schedules/{scheduleId}` removes one. This is how teams keep weekly resilience drills running without manual triggers.

### Can I limit what my agent is allowed to do with the Gremlin API?

Yes. Because you run Jentic One yourself, your own rules decide which Gremlin operations and credentials the agent may use. Since Gremlin puts scenario and attack IDs in the URL path (`/scenarios/{scenarioId}`, `/attacks/{attackGuid}`), a rule can pin the agent to a single scenario so it only reads that scenario and its runs and nothing else. You pick the operations it may call, so destructive ones like launching an attack with POST /attacks or halting every attack with DELETE `/attacks/active` are excluded unless you add them.