Gremlin services API

openapi: 3.2.0
info:
  title: Gremlin agents Services 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: services
  description: Get metrics about intelligent health check target for a service
paths:
  /services/{serviceId}/metrics/{awsResource}:
    get:
      tags:
      - services
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getMetrics
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: awsResource
        in: path
        required: true
        schema:
          type: string
      - name: startTime
        in: query
        schema:
          type: integer
          format: int64
      - name: endTime
        in: query
        schema:
          type: integer
          format: int64
      - name: statusCheck
        in: query
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/MetricResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
  /services/{serviceId}/dependencies:
    get:
      tags:
      - services
      summary: Paginated endpoint for listing active dependencies for a given service
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getActiveDependencies
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: pageSize
        in: query
        description: This value determines how many results will be returned per call.
        schema:
          type: integer
          format: int32
        example: None (unlimited)
      - name: pageToken
        in: query
        description: Token corresponding to the last page of customer services retrieved. Pass the pageToken to get the next page of customer services. Only pageNumber or pageToken accepted along with pageSize
        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/PagedResponseDependencyResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
    post:
      tags:
      - services
      summary: Manually define a new dependency for a given Service
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: defineDependency
      parameters:
      - name: serviceId
        in: path
        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/DefineDependencyRequest'
        required: true
      responses:
        default:
          description: default response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DependencyResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/dependencies/discovered:
    delete:
      tags:
      - services
      summary: Deletes all discovered dependencies, including those marked as ignored, for the specified service. Halts any active runs if necessary and updates the service's reliability score.
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: deleteAllDiscoveredDependencies
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: confirm
        in: query
        schema:
          type: boolean
          default: false
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/dependencies/ignored:
    get:
      tags:
      - services
      summary: Paginated endpoint for listing ignored dependencies for a given service
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getIgnoredDependencies
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: pageSize
        in: query
        description: This value determines how many results will be returned per call.
        schema:
          type: integer
          format: int32
        example: None (unlimited)
      - name: pageToken
        in: query
        description: Token corresponding to the last page of customer services retrieved. Pass the pageToken to get the next page of customer services. Only pageNumber or pageToken accepted along with pageSize
        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/PagedResponseDependencyResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
    delete:
      tags:
      - services
      summary: Delete all dependencies that are marked ignored
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: deleteAllIgnoredDependencies
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/dependencies/{dependencyId}:
    delete:
      tags:
      - services
      summary: Mark a dependency as ignored, removing it from the list of active dependencies and reliability score.
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: deleteDependency
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: dependencyId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            '*/*': {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
    patch:
      tags:
      - services
      summary: Update a dependency's name and/or isSPOF flag. We deliberately do not allow updating a dependency's endpoint, i.e. address and port, because updating either of these values effectively changes the dependency. To change these values, refer to delete and define APIs.
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: updateDependency
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: dependencyId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/UpdateDependencyRequest'
        required: true
      responses:
        '200':
          description: Updates dependency's name and/or isSPOF flag
        '400':
          description: Bad Request
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
        '404':
          description: Not found
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/dependencies/ignored/{dependencyId}:
    delete:
      tags:
      - services
      summary: Delete a dependency that is marked as ignored
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: deleteIgnoredDependency
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: dependencyId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            '*/*': {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/dependencies/{dependencyId}/name:
    put:
      tags:
      - services
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: renameDependency
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: dependencyId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      requestBody:
        content:
          text/plain:
            schema:
              maxLength: 253
              minLength: 0
              type: string
        required: true
      responses:
        default:
          description: default response
          content:
            '*/*': {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      deprecated: true
      security:
      - privilege:
        - SERVICES_WRITE
  /services:
    get:
      tags:
      - services
      summary: Paginated endpoint for fetching services for a given team
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getAllServices
      parameters:
      - name: pageSize
        in: query
        description: This value determines how many results will be returned per call.
        schema:
          type: integer
          format: int32
        example: None (unlimited)
      - name: pageToken
        in: query
        description: Token corresponding to the last page of customer services retrieved. Pass the pageToken to get the next page of customer services
        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/PagedResponseUserDefinedServiceResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
    post:
      tags:
      - services
      summary: Create a service
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: createService
      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/UserDefinedServiceRequest'
        required: true
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                type: string
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
    patch:
      tags:
      - services
      summary: Bulk add a given Status Check to all services
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: bulkAddHealthChecksToServices
      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/BulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Bulk updates services with health checks
        '400':
          description: Bad Request
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
        '404':
          description: Not found
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
      security:
      - privilege:
        - SERVICES_WRITE
  /services/bulk-create-with-load-balancers:
    post:
      tags:
      - services
      summary: Bulk create services based on AWS Load balancers
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: bulkCreateWithLoadBalancers
      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/BulkCreateServicesFromLoadBalancersRequest'
        required: true
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/bulk-delete:
    post:
      tags:
      - services
      summary: Bulk delete services
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: bulkDeleteServices
      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/BulkDeleteRequest'
        required: true
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/service-creation-readiness/clients:
    post:
      tags:
      - services
      summary: Retrieves clients for a potential service definition
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: computeServiceReadinessAgentsFromPodUIDs
      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/ServiceReadinessAgentsFromPodUIDsRequest'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceReadinessClientsResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}:
    get:
      tags:
      - services
      summary: Retrieve a service by id
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getService
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Not Found
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
    delete:
      tags:
      - services
      summary: Permanently delete a service
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: delete_6
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
    patch:
      tags:
      - services
      summary: Update a service, editing some fields
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: update_4
      parameters:
      - name: serviceId
        in: path
        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/ServiceUpdateRequest'
        required: true
      responses:
        '200':
          description: Updates a Service.
        '404':
          description: Not found
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_WRITE
  /services/all-for-company:
    get:
      tags:
      - services
      summary: Paginated endpoint for fetching services for a given company
      description: Requires the privilege [`DISASTER_RECOVERY_TESTS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getAllServicesForCompany
      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: Token corresponding to the last page of customer services retrieved. Pass the pageToken to get the next page of customer services
        schema:
          type: string
        example: None (returns first page)
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResponseUserDefinedServiceResponse'
        '403':
          description: 'User requires privilege: DISASTER_RECOVERY_TESTS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - DISASTER_RECOVERY_TESTS_WRITE
  /services/{id}/risk-summary:
    get:
      tags:
      - services
      summary: Load risk evaluations for service. Re-evaluate risks if service has been deployed since the last evaluation.
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getRiskSummary
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - 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/DetailedServiceRiskSummaryResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
  /services/service-creation-readiness/{targetType}:
    get:
      tags:
      - services
      description: Requires the privilege [`SERVICES_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getServiceCreationReadiness
      parameters:
      - name: targetType
        in: path
        required: true
        schema:
          type: string
      - 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/ServiceCreationReadinessForOwnedAndSharedAssetsResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      deprecated: true
      security:
      - privilege:
        - SERVICES_WRITE
  /services/{serviceId}/score:
    get:
      tags:
      - services
      summary: Retrieve a service's score in plain/text
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getServiceScore
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Not Found
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
  /services/{serviceId}/status-checks:
    get:
      tags:
      - services
      summary: Fetch Status Checks associated with a given service
      description: Requires the privilege [`SERVICES_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getStatusChecksForService
      parameters:
      - name: serviceId
        in: path
        required: true
        schema:
          type: string
      - 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/ServiceStatusCheckResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_READ
  /services/{serviceId}/baseline:
    post:
      tags:
      - services
      summary: Run RM tests for a given service
      description: "By default this endpoint initiates all RM Tests in your Test Suite for this service and every one of it's dependencies. \nYou may also supply a list of RM tests in the body if you which to constrain to a subset of all tests, but they *must* be in the active Test Suite for your team\nRequires the privilege [`SERVICES_RUN`](https://www.gremlin.com/docs/user-management/access-control/#privileges)"
      operationId: runAllTests
      parameters:
      - name: serviceId
        in: path
        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/StartBaselineRequest'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSeriesRunResponse'
        '403':
          description: 'User requires privilege for target team: SERVICES_RUN'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - SERVICES_RUN
components:
  schemas:
    Trigger:
      required:
      - dayOfWeek
      - scheduleWindows
      type: object
      properties:
        dayOfWeek:
          type: string
          enum:
          - M
          - T
          - W
          - Th
          - F
          - S
          - Su
        scheduleWindows:
          maxItems: 1
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/ScheduleWindow'
    TestSeriesRunResponse:
      type: object
      properties:
        teamId:
          type: string
        serviceId:
          type: string
        startTime:
          type: string
          format: date-time
        pauseUntil:
          type: string
          format: date-time
        pauseReason:
          type: string
        tests:
          type: array
          items:
            type: string
        currentTestIndex:
          type: integer
          format: int64
        createdBy:
          type: string
        state:
          type: string
          enum:
          - PENDING
          - ACTIVE
          - FINISHED
          - HALTED
          - FAILED
    ScheduleSettings:
      type: object


# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gremlin/refs/heads/main/openapi/gremlin-services-api-openapi.yml