SpecterOps Search API

openapi: 3.2.0
info:
  title: BloodHound Search 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: Search
paths:
  /api/v2/search:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: Search
      summary: Search for objects
      description: Search for graph objects by name or object ID, filtered by type.
      tags:
      - Search
      parameters:
      - name: q
        description: Search parameter for the name or object ID of a node.
        in: query
        required: true
        schema:
          type: string
      - name: type
        description: 'Node type. Currently only supports built-in types.

          Some AD examples: `Base`, `User`, `Computer`, `Group`, `Container`.

          Some Azure examples: `AZBase`, `AZApp`, `AZDevice`.

          '
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/model.search-result'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/available-domains:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: GetAvailableDomains
      summary: Get available domains
      description: Gets available domains along with their collection status
      tags:
      - Search
      parameters:
      - name: sort_by
        description: Sortable columns are objectid, name.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: objectid
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: collected
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/model.domain-selector'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '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
    too-many-requests:
      description: '**Too Many Requests**

        The client has sent too many requests within a certain time window

        and tripped the rate limiting middleware.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 429
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: middleware
              message: Too many requests. Please try again later.
    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.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
    null.int32:
      type: object
      properties:
        int32:
          type: integer
          format: int32
        valid:
          description: Valid is true if `int32` is not `null`.
          type: boolean
    null.boolean:
      type: object
      properties:
        bool:
          type: boolean
        valid:
          description: Valid is true if `boolean` is not `null`
          type: boolean
    model.search-result:
      type: object
      properties:
        objectid:
          type: string
          readOnly: true
        type:
          type: string
          readOnly: true
        name:
          type: string
          readOnly: true
        distinguishedname:
          type: string
          readOnly: true
        system_tags:
          type: string
          readOnly: true
    model.asset-group-tag:
      type: object
      properties:
        id:
          type: integer
        type:
          type: integer
        kind_id:
          type: integer
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
        position:
          $ref: '#/components/schemas/null.int32'
        require_certify:
          $ref: '#/components/schemas/null.boolean'
        analysis_enabled:
          $ref: '#/components/schemas/null.boolean'
        glyph:
          $ref: '#/components/schemas/null.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.domain-selector:
      type: object
      properties:
        type:
          type: string
          readOnly: true
        name:
          type: string
          readOnly: true
        id:
          type: string
          readOnly: true
        collected:
          type: boolean
          readOnly: true
        environment_kind_id:
          type: integer
          readOnly: true
          description: OpenGraph environment kind ID for custom environments
        environment_kind_display_name:
          type: string
          readOnly: true
          description: Human-readable display name for the node's environment kind
        impactValue:
          type: integer
          readOnly: true
          description: Enterprise Only
        hygiene_attack_paths:
          type: integer
          readOnly: true
          description: Enterprise Only
        exposures:
          type: array
          readOnly: true
          description: Enterprise Only
          items:
            type: object
            properties:
              exposure_percent:
                type: integer
                readOnly: true
              asset_group_tag:
                $ref: '#/components/schemas/model.asset-group-tag'
    api.params.query.skip:
      type: integer
      minimum: 0
      description: The number of items to skip in a paginated response.
    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
    null.string:
      type: object
      properties:
        string:
          type: string
        valid:
          description: Valid is true if `string` is not `null`
          type: boolean
  parameters:
    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.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'
    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]+)$
  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