Gremlin scenarios API
Create, update, run, halt, and list scenarios
Create, update, run, halt, and list scenarios
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