Gremlin scenarios API
Create, update, run, halt, and list scenarios
Create, update, run, halt, and list scenarios
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/gremlin-scenarios-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.1
info:
title: Gremlin agents scenarios API
description: The API for interacting with the Gremlin Failure-as-a-Service platform
termsOfService: https://www.gremlin.com/terms_of_service_2017_03_24
contact:
name: Gremlin Support
email: support@gremlin.com
license:
name: Gremlin License
url: https://www.gremlin.com/license_2017_03_24
version: '1.0'
servers:
- url: https://api.gremlin.com/v1
description: Gremlin API v1
tags:
- name: scenarios
description: Create, update, run, halt, and list scenarios
paths:
/scenarios/{scenarioId}/runs/{runNumber}/images/{imageName}:
delete:
tags:
- scenarios
summary: Deletes a given images associated with a given scenario
description: Requires the privilege [`IMAGES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: deleteImage
parameters:
- name: imageName
in: path
required: true
schema:
type: string
- name: scenarioId
in: path
required: true
schema:
type: string
- name: runNumber
in: path
required: true
schema:
type: integer
format: int64
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
default:
description: default response
content:
text/plain: {}
'403':
description: 'User requires privilege for target team: IMAGES_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- IMAGES_WRITE
patch:
tags:
- scenarios
summary: Uploads an image to a given scenario
description: "This takes an image as a multipart/form-data (parameter name \"file\") and uploads it to Gremlin's backend and associates it with a given ScenarioRun. \nNOTE: imageNames must be S3 compatible strings ([a-zA-Z0-9!-_'\\(\\)]) with under 1000 characters (including file type)\nRequires the privilege [`IMAGES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)"
operationId: addImage
parameters:
- name: imageName
in: path
required: true
schema:
maxLength: 987
minLength: 0
pattern: '[a-zA-Z0-9\!\-\_\.\*\''\(\)\ ]+'
type: string
- name: scenarioId
in: path
required: true
schema:
type: string
- name: runNumber
in: path
required: true
schema:
type: integer
format: int64
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
$ref: '#/components/schemas/FormDataContentDisposition'
responses:
default:
description: default response
content:
text/plain: {}
'403':
description: 'User requires privilege for target team: IMAGES_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- IMAGES_WRITE
/scenarios/{guid}/archive:
post:
tags:
- scenarios
summary: Archive a scenario.
description: Requires the privilege [`SCENARIOS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: archive
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
description: Indicates the scenario updated in place. Call GET v1/scenario/{guid} to retrieve the latest state
'404':
description: scenario not found
'403':
description: 'User requires privilege for target team: SCENARIOS_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_WRITE
/scenarios:
get:
tags:
- scenarios
summary: List all runnable scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getRunnable
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
post:
tags:
- scenarios
summary: Create a new scenario.
description: 'Creates a new scenario based on the Scenario Graph provided
Requires the privilege [`SCENARIOS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)'
operationId: createNewScenario
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScenarioRequest'
responses:
'200':
description: The id for the created scenario
content:
text/plain:
schema:
type: string
'400':
description: Bad Request
'402':
description: Payment Required
'403':
description: 'User requires privilege for target team: SCENARIOS_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_WRITE
/scenarios/shared:
get:
tags:
- scenarios
summary: Get all scenarios shared with this team.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getScenariosSharedWithTeam
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SharedScenarioResponse'
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/SharedScenarioResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
post:
tags:
- scenarios
summary: Create new shared scenarios.
description: Requires the privilege [`SCENARIO_SHARE_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: createNewSharedScenario
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
responses:
'201':
description: Shared scenarios created
'400':
description: Bad request
'403':
description: 'User requires privilege for target team: SCENARIO_SHARE_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIO_SHARE_WRITE
/scenarios/{guid}:
get:
tags:
- scenarios
summary: Get details about a scenario.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getScenario
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScenarioResponse'
'404':
description: scenario not found
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
put:
tags:
- scenarios
summary: Update a scenario
description: Requires the privilege [`SCENARIOS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: updateScenario
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScenarioRequest'
responses:
'200':
description: Indicates the scenario updated in place. Call GET v1/scenario/{guid} to retrieve the latest state
'400':
description: Bad Request
'402':
description: Payment Required
'403':
description: 'User requires privilege for target team: SCENARIOS_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_WRITE
delete:
tags:
- scenarios
summary: Delete a scenario.
description: Requires the privilege [`SCENARIOS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: delete_4
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'404':
description: scenario not found
'400':
description: scenario cannot be deleted until it is unshared
'403':
description: 'User requires privilege for target team: SCENARIOS_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_WRITE
/scenarios/active:
get:
tags:
- scenarios
summary: List all active scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getActive_1
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/active-runs:
get:
tags:
- scenarios
summary: List all active scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getActiveRuns
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/PagedResponseScenarioRunResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/runs:
get:
tags:
- scenarios
summary: List all scenario runs for your team.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getAllRunsForTeam
parameters:
- name: state
in: query
schema:
type: string
- name: includeArchived
in: query
schema:
type: string
- name: startDate
in: query
schema:
type: string
- name: endDate
in: query
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioRunResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/archived:
get:
tags:
- scenarios
summary: List all archived scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getArchived
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/drafts:
get:
tags:
- scenarios
summary: List all draft scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getDrafts
parameters:
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/active/paged:
get:
tags:
- scenarios
summary: Get a team's active FI scenario runs ordered by start time desc.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getPaginatedActiveRuns
parameters:
- name: pageSize
in: query
description: This value determines how many results will be returned per call.
schema:
type: integer
format: int32
default: 1000
example: None (defaults to 1000)
- name: pageToken
in: query
description: Pass the pageToken to get the next page of active FI scenario runs
schema:
type: string
example: None (returns first page)
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/PagedResponseScenarioRunResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/completed/paged:
get:
tags:
- scenarios
summary: Get a team's completed FI scenario runs ordered by start time desc.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getPaginatedCompletedScenarioRuns
parameters:
- name: pageSize
in: query
description: This value determines how many results will be returned per call.
schema:
type: integer
format: int32
default: 1000
example: None (defaults to 1000)
- name: pageToken
in: query
description: Pass the pageToken to get the next page of completed reliability test runs
schema:
type: string
example: None (returns first page)
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/PagedResponseCompletedScenarioRunResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/{guid}/runs:
get:
tags:
- scenarios
summary: List all runs for a scenario.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getRuns
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: startDate
in: query
schema:
type: string
- name: endDate
in: query
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioRunResponse'
'404':
description: scenario not found
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
post:
tags:
- scenarios
summary: Run a scenario.
description: Requires the privilege [`SCENARIOS_RUN`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: runScenario
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RunScenarioRequest'
responses:
'200':
description: The run number for the new run in-progress
content:
text/plain:
schema:
type: integer
format: int64
'400':
description: Bad Request
'402':
description: Payment Required
'404':
description: '{guid} not found'
'409':
description: Scenario run number {runNumber} is in progress
'403':
description: 'User requires privilege for target team: SCENARIOS_RUN'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_RUN
/scenarios/{guid}/runs/paged:
get:
tags:
- scenarios
summary: Paged list runs for a scenario. Scenarios are monotonically increasing and use their run number as the pagination key
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getRunsPaged
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: runNumber
in: query
schema:
minimum: 1
type: integer
format: int64
- name: limit
in: query
schema:
type: integer
format: int32
default: 1000
- name: forward
in: query
description: Used to indicate querying forward or backwards from the supplied runNumber (defaults to forward)
schema:
type: boolean
default: true
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'404':
description: scenario not found, or no runs found for that scenario
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/{guid}/runs/{runNumber}:
get:
tags:
- scenarios
summary: Get details about a scenario run.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getScenarioRun
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: runNumber
in: path
required: true
schema:
type: integer
format: int64
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioRunResponse'
'400':
description: Bad Request
'402':
description: Payment Required
'404':
description: scenario run not found
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/{guid}/schedules:
get:
tags:
- scenarios
summary: Get all schedules for a scenario.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getScenarioSchedules
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioScheduleResponse'
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
/scenarios/shared/{guid}:
get:
tags:
- scenarios
summary: Get details on a shared scenarios.
description: Requires the privilege [`SCENARIOS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: getSharedScenario
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SharedScenarioResponse'
text/plain:
schema:
$ref: '#/components/schemas/SharedScenarioResponse'
'400':
description: Bad Request
'404':
description: shared scenario not found
'403':
description: 'User requires privilege for target team: SCENARIOS_READ'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIOS_READ
delete:
tags:
- scenarios
summary: Unshare a company shared scenario.
description: Requires the privilege [`SCENARIO_SHARE_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: unshareScenario
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
responses:
'400':
description: Bad Request
'404':
description: shared scenario not found
'403':
description: 'User requires privilege for target team: SCENARIO_SHARE_WRITE'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
security:
- privilege:
- SCENARIO_SHARE_WRITE
/scenarios/halt:
post:
tags:
- scenarios
summary: Idempotently halt all scenario runs and active attacks.
operationId: haltAsPost_2
parameters:
- name: teamId
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HaltRequest'
responses:
'202':
description: Scenario has begun halting
'403':
description: 'User requires privilege: HALT_ALL'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
/scenarios/halt/{guid}/runs/{runNumber}:
post:
tags:
- scenarios
summary: Idempotently halt the specified scenario run.
description: Requires the privilege [`MINIMUM_TEAM_PRIVILEGES`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
operationId: haltAsPost_3
parameters:
- name: guid
in: path
description: This value represents the globally unique identifier of the record to fetch.
required: true
schema:
type: string
- name: runNumber
in: path
required: true
schema:
type: integer
format: int64
- name: teamId
in: query
description: Required when using company session token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HaltRequest'
responses:
'202':
description: Scenario has begun halting
'404':
description: scenario not found
'403':
description: 'User requires privilege for target team: MINIMUM_TEAM_PRIVILEGES'
'401':
description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
securit
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gremlin/refs/heads/main/openapi/gremlin-scenarios-api-openapi.yml