SpecterOps Events (Schedules) API

openapi: 3.2.0
info:
  title: BloodHound Events (Schedules) API
  contact:
    name: BloodHound Enterprise Support
    url: https://bloodhound.specterops.io/
    email: support@specterops.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: v2
  description: This is the API that drives BloodHound Enterprise and Community Edition.
servers:
- url: /
  description: This is the base path for all endpoints, relative to the domain where the API is being hosted.
security:
- JWTBearerToken: []
- SignedRequest: []
  RequestDate: []
  HMACSignature: []
tags:
- name: Events (Schedules)
paths:
  /api/v2/events:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: ListClientSchedules
      summary: List events
      description: Gets all client scheduled events.
      tags:
      - Events (Schedules)
      parameters:
      - name: sort_by
        description: Sortable columns are `next_scheduled_at`, `id`, `created_at`, `updated_at`, `deleted_at`.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - name: id
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.integer'
      - name: rrule
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: next_scheduled_at
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.time'
      - $ref: '#/components/parameters/query.clients.job.client-id'
      - $ref: '#/components/parameters/query.clients.job.session-collection'
      - $ref: '#/components/parameters/query.clients.job.local-group-collection'
      - $ref: '#/components/parameters/query.clients.job.ad-structure-collection'
      - $ref: '#/components/parameters/query.clients.job.cert-services-collection'
      - $ref: '#/components/parameters/query.clients.job.ca-registry-collection'
      - $ref: '#/components/parameters/query.clients.job.dc-registry-collection'
      - $ref: '#/components/parameters/query.clients.hydrate-domains'
      - $ref: '#/components/parameters/query.clients.hydrate-ous'
      - $ref: '#/components/parameters/query.created-at'
      - $ref: '#/components/parameters/query.updated-at'
      - $ref: '#/components/parameters/query.deleted-at'
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/model.client-schedule-display'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal-server-error'
    post:
      operationId: CreateClientSchedule
      summary: Create Event
      description: Creates a scheduled event for data collection
      tags:
      - Events (Schedules)
      requestBody:
        description: The request body for creating an event
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.client-schedule'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.client-schedule-display'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/events/{event_id}:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: event_id
      description: Event ID
      in: path
      required: true
      schema:
        type: integer
        format: int32
    get:
      operationId: GetClientSchedule
      summary: Get Event
      description: Gets a scheduled job event by ID.
      tags:
      - Events (Schedules)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.client-schedule-display'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/internal-server-error'
    put:
      operationId: UpdateClientEvent
      summary: Update Event
      description: Updates a scheduled event
      tags:
      - Events (Schedules)
      requestBody:
        description: The request body for updating an event
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.client-schedule'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.client-schedule-display'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/internal-server-error'
    delete:
      operationId: DeleteClientEvent
      summary: Delete Event
      description: Deletes a scheduled event and associated tasks by id
      tags:
      - Events (Schedules)
      responses:
        '200':
          $ref: '#/components/responses/no-content'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '500':
          $ref: '#/components/responses/internal-server-error'
components:
  responses:
    forbidden:
      description: '**Forbidden**

        This is most commonly caused by an authenticated client trying to

        access a resource that it does not have permission for.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 403
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: You do not have permission to access this resource
    internal-server-error:
      description: '**Internal Server Error**

        This is usually the result of either an unexpected database or application error.

        The client may try modifying or resending the request, but the error is likely not related to the client

        doing something wrong.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 500
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The request could not be handled due to an unexpected database error.
    unauthorized:
      description: '**Unauthorized**

        This endpoint failed an authentication requirement. Either the client tried to access

        a protected endpoint without being authenticated, or an auth validation failed (ex- invalid

        credentials or expired token).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 401
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: login
              message: Unauthorized
    not-found:
      description: '**Not Found**

        This error typically comes from operations where a valid ID was passed to the request

        to look up an entity but the entity could not be found.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 404
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The requested client could not be found.
    no-content:
      description: '**No Content**

        This response will contain no response body.

        '
      content:
        text/plain:
          schema:
            type: string
          example: '[this request has no response data]'
    bad-request:
      description: '**Bad Request**

        This could be due to one of the following reasons:

        - JSON payload is missing or malformed

        - Path or query parameters are missing or invalid/malformed

        - The data sent is not valid (ex- sending a `string` in an `integer` field)

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 400
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: The JSON payload could not be unmarshalled.
  schemas:
    api.params.query.limit:
      type: integer
      minimum: 0
      description: The limit of results requested by the client.
    api.params.predicate.filter.integer:
      type: string
      pattern: ^((eq|neq|gt|gte|lt|lte):)?-?[0-9]+$
      description: 'Filter results by column integer value. Valid filter predicates are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.

        '
    model.components.int32.id:
      type: object
      properties:
        id:
          type: integer
          format: int32
          readOnly: true
          description: This is the unique identifier for this object.
    null.time:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: An RFC-3339 formatted string
        valid:
          description: Valid is true if `time` is not `null`.
          type: boolean
    api.error-detail:
      type: object
      properties:
        context:
          type: string
          description: The context in which the error took place
        message:
          type: string
          description: A human-readable description of the error
    api.params.query.sort-by:
      type: string
      description: 'Sort by column. Can be used multiple times; prepend a hyphen for descending order.

        See parameter description for details about which columns are sortable.

        '
    model.components.timestamps:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        deleted_at:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/null.time'
    model.domain-details:
      allOf:
      - $ref: '#/components/schemas/model.components.base-ad-entity'
      - type: object
        properties:
          type:
            type: string
    api.params.predicate.filter.string:
      type: string
      pattern: ^((eq|~eq|neq):)?[^:]+$
      description: 'Filter results by column string value. Valid filter predicates are `eq`, `~eq`, `neq`.

        '
    model.ou-details:
      allOf:
      - $ref: '#/components/schemas/model.components.base-ad-entity'
      - type: object
        properties:
          distinguishedname:
            type:
            - string
            - 'null'
          type:
            type:
            - string
            - 'null'
    api.params.predicate.filter.time:
      type: string
      pattern: ^((eq|neq|gt|gte|lt|lte):)?[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|-[0-9]{2}:[0-9]{2})$
      description: 'Filter results by column timestamp value formatted as an RFC-3339 string.

        Valid filter predicates are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.

        '
    api.response.pagination:
      type: object
      properties:
        count:
          type: integer
          minimum: 0
          description: The total number of results.
        skip:
          $ref: '#/components/schemas/api.params.query.skip'
        limit:
          $ref: '#/components/schemas/api.params.query.limit'
    model.client-schedule-display:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - type: object
        properties:
          client_id:
            type: string
            format: uuid
          rrule:
            type: string
          session_collection:
            type: boolean
          local_group_collection:
            type: boolean
          ad_structure_collection:
            type: boolean
          cert_services_collection:
            type: boolean
          ca_registry_collection:
            type: boolean
          dc_registry_collection:
            type: boolean
          all_trusted_domains:
            type: boolean
          ous:
            type: array
            items:
              $ref: '#/components/schemas/model.ou-details'
          domains:
            type: array
            items:
              $ref: '#/components/schemas/model.domain-details'
    api.params.query.skip:
      type: integer
      minimum: 0
      description: The number of items to skip in a paginated response.
    model.components.base-ad-entity:
      type: object
      properties:
        objectid:
          type: string
        name:
          type:
          - string
          - 'null'
        exists:
          type:
          - boolean
          - 'null'
    api.error-wrapper:
      type: object
      description: ''
      properties:
        http_status:
          type: integer
          description: The HTTP status code
          minimum: 100
          maximum: 600
        timestamp:
          type: string
          format: date-time
          description: The RFC-3339 timestamp in which the error response was sent
        request_id:
          type: string
          format: uuid
          description: The unique identifier of the request that failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/api.error-detail'
          description: The error(s) that occurred from processing the request
    api.params.predicate.filter.boolean:
      type: string
      pattern: ^((eq|neq):)?(t|T|TRUE|true|True|f|F|FALSE|false|False)$
      description: 'Filter results by column boolean value. Valid filter predicates are `eq`, `neq`.

        '
    api.params.predicate.filter.uuid:
      type: string
      pattern: ^((eq|neq):)?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      description: 'Filter results by column string-formatted uuid value. Valid filter predicates are `eq`, `neq`.

        '
    model.client-schedule:
      allOf:
      - $ref: '#/components/schemas/model.components.int32.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          client_id:
            type: string
            format: uuid
            readOnly: true
          rrule:
            type: string
          session_collection:
            type: boolean
          local_group_collection:
            type: boolean
          ad_structure_collection:
            type: boolean
          cert_services_collection:
            type: boolean
          ca_registry_collection:
            type: boolean
          dc_registry_collection:
            type: boolean
          all_trusted_domains:
            type: boolean
          next_scheduled_at:
            type: string
            format: date-time
            readOnly: true
          ous:
            type: array
            items:
              type: string
          domains:
            type: array
            items:
              type: string
  parameters:
    query.clients.job.ca-registry-collection:
      name: ca_registry_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
    query.updated-at:
      name: updated_at
      in: query
      description: Filter results by `updated_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    query.clients.job.client-id:
      name: client_id
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.uuid'
    query.created-at:
      name: created_at
      in: query
      description: Filter results by `created_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    query.limit:
      name: limit
      description: This query parameter is used for setting an upper limit of objects returned in paginated responses.
      in: query
      schema:
        $ref: '#/components/schemas/api.params.query.limit'
    query.clients.job.ad-structure-collection:
      name: ad_structure_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
    query.clients.hydrate-ous:
      name: hydrate_ous
      description: When a value of `true` is passed, any OUs associated with scheduled and finished jobs for each client will have expanded properties including `name` and `type`. When a value of `false` is passed, these same OUs will only return as a list of `objectid`s.
      in: query
      schema:
        type: boolean
        default: true
    query.skip:
      name: skip
      description: This query parameter is used for determining the number of objects to skip in pagination.
      in: query
      schema:
        $ref: '#/components/schemas/api.params.query.skip'
    query.deleted-at:
      name: deleted_at
      in: query
      description: Filter results by `deleted_at` value. See filter schema details for valid predicates.
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.time'
    query.clients.job.dc-registry-collection:
      name: dc_registry_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
    query.clients.hydrate-domains:
      name: hydrate_domains
      description: When a value of `true` is passed, any Domains associated with scheduled and finished jobs for each client will have expanded properties including `name` and `type`. When a value of `false` is passed, these same Domains will only return as a list of `objectid`s.
      in: query
      schema:
        type: boolean
        default: true
    query.clients.job.cert-services-collection:
      name: cert_services_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
    header.prefer:
      name: Prefer
      description: Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled.
      in: header
      required: false
      schema:
        type: string
        default: wait=30
        pattern: ^wait=(-1|[0-9]+)$
    query.clients.job.session-collection:
      name: session_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
    query.clients.job.local-group-collection:
      name: local_group_collection
      in: query
      schema:
        $ref: '#/components/schemas/api.params.predicate.filter.boolean'
  securitySchemes:
    JWTBearerToken:
      description: '`Authorization: Bearer $JWT_TOKEN`

        '
      type: http
      scheme: bearer
      bearerFormat: JWT
    SignedRequest:
      description: '`Authorization: bhesignature $TOKEN_ID`

        '
      type: apiKey
      name: Authorization
      in: header
    RequestDate:
      description: '`RequestDate: $RFC3339_DATETIME`

        '
      type: apiKey
      name: RequestDate
      in: header
    HMACSignature:
      description: '`Signature: $BASE64ENCODED_HMAC_SIGNATURE`

        '
      type: apiKey
      name: Signature
      in: header
x-tagGroups:
- name: Community & Enterprise
  tags:
  - Auth
  - Roles
  - Permissions
  - API Tokens
  - BloodHound Users
  - Collectors
  - Collection Uploads
  - Custom Node Management
  - API Info
  - Search
  - Audit
  - Config
  - Asset Isolation
  - Graph
  - Azure Entities
  - AD Base Entities
  - Computers
  - Containers
  - Domains
  - GPOs
  - AIA CAs
  - Root CAs
  - Enterprise CAs
  - NT Auth Stores
  - Cert Templates
  - OUs
  - AD Users
  - Groups
  - Data Quality
  - Datapipe
  - Cypher
  - OpenGraph (Experimental)
- name: Enterprise Only
  tags:
  - EULA
  - BHE Users
  - Analysis
  - Client Ingest
  - Clients
  - Jobs
  - Tasks
  - Events (Schedules)
  - Attack Paths
  - Risk Posture
  - Meta Entities
  - Alerts