SpecterOps Cypher API

openapi: 3.2.0
info:
  title: BloodHound Cypher 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: Cypher
paths:
  /api/v2/saved-queries:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    get:
      operationId: ListSavedQueries
      summary: List saved queries
      description: Get all saved queries for the current user
      tags:
      - Cypher
      parameters:
      - $ref: '#/components/parameters/query.skip'
      - $ref: '#/components/parameters/query.limit'
      - name: sort_by
        description: Sortable columns are user_id, name, query, id, created_at, updated_at, deleted_at.
        in: query
        schema:
          $ref: '#/components/schemas/api.params.query.sort-by'
      - name: name
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: query
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: user_id
        in: query
        schema:
          $ref: '#/components/schemas/api.params.predicate.filter.string'
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - all
          - owned
          - shared
          - public
          default: owned
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/api.response.pagination'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        allOf:
                        - type: object
                          properties:
                            scope:
                              type: string
                        - $ref: '#/components/schemas/model.saved-query'
        '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'
    post:
      operationId: CreateSavedQuery
      summary: Create a saved query
      description: Create a new saved query
      tags:
      - Cypher
      requestBody:
        description: The request body for creating a saved query
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.saved-query'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.saved-query'
        '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/saved-queries/{saved_query_id}:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: saved_query_id
      description: ID of the saved query
      in: path
      required: true
      schema:
        type: integer
        format: int32
    get:
      operationId: GetSavedQuery
      summary: Return a saved query
      description: Returns an existing saved query by ID
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.saved-query'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
    delete:
      operationId: DeleteSavedQuery
      summary: Delete a saved query
      description: Delete an existing saved query by ID
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          $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'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
    put:
      operationId: UpdateSavedQuery
      summary: Update a saved query
      description: Update an existing saved query by ID
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: The request body for updating a saved query
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.saved-query'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.saved-query'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/saved-queries/{saved_query_id}/permissions:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    - name: saved_query_id
      description: ID of the saved query
      in: path
      required: true
      schema:
        type: integer
        format: int32
    get:
      operationId: GetSavedQueryPermissions
      summary: Retrieves saved query permissions for provided query id
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.saved-queries-permissions.response'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
    delete:
      operationId: DeleteSavedQueryPermissions
      summary: Revokes permission of a saved query from users
      description: Revokes permission of a saved query from a given set of users
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: The request body for revoking permissions of a saved query from users
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_ids:
                  type: array
                  description: A list of user ids that will have their permission revoked from the given saved query
                  items:
                    type: string
                    format: uuid
      responses:
        '204':
          $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'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
    put:
      operationId: ShareSavedQuery
      summary: Share a saved query or set it to public
      description: Shares an existing saved query or makes it public
      tags:
      - Cypher
      parameters:
      - name: saved_query_id
        description: ID of the saved query
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: The request body for sharing a saved query or making it public
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                public:
                  type: boolean
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/model.saved-queries-permissions'
        '204':
          $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'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/saved-queries/{saved_query_id}/export:
    parameters:
    - name: saved_query_id
      description: ID of the saved query
      in: path
      required: true
      schema:
        type: integer
        format: int32
    get:
      operationId: ExportSavedQuery
      summary: Export a saved query
      description: Export an existing saved query by ID
      tags:
      - Cypher
      responses:
        '200':
          description: "**OK**\nThis response will contain binary content.\n\nThe response ZIP file will contain JSON files using their query name as the file name.\nThe underlying JSON file is expected to have the following structure:\n```json\n{\n \"name\": \"Return_Nodes\",\n \"query\": \"MATCH (n) RETURN n\",\n \"description\": \"Returns all nodes in a given graph\"\n}\n```\n"
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              example: '[this request has a binary response]'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/saved-queries/import:
    post:
      operationId: ImportSavedQueries
      summary: Import one or more cypher queries
      description: 'Import one or more cypher queries.


        The request body should be a json file containing a single query or a Zip consisting of multiple JSON files each containing a single query.


        The underlying JSON file(s) is expected to have the following structure:

        ```json

        {

        "name": "Return_Nodes",

        "query": "MATCH (n) RETURN n",

        "description": "Returns all nodes in a given graph"

        }

        ```'
      tags:
      - Cypher
      requestBody:
        description: Request body should be a JSON or Zip file.
        required: true
        content:
          application/json:
            schema:
              type: string
              format: binary
          application/zip:
            schema:
              type: string
              format: binary
      responses:
        '201':
          $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'
        '415':
          $ref: '#/components/responses/unsupported-media-type'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/saved-queries/export:
    parameters:
    - name: scope
      description: Scope of saved queries, only the first scope parameter is used.
      in: query
      required: true
      schema:
        type: string
        enum:
        - all
        - public
        - shared
        - owned
    get:
      operationId: ExportSavedQueries
      summary: Export one or more saved queries
      description: Export existing saved queries using the scope parameter.
      tags:
      - Cypher
      responses:
        '200':
          description: "**OK**\nThis response will contain binary content.\n\nThe response ZIP file will contain JSON files using their query name as the file name.\nThe underlying JSON file is expected to have the following structure:\n```json\n{\n \"name\": \"Return_Nodes\",\n \"query\": \"MATCH (n) RETURN n\",\n \"description\": \"Returns all nodes in a given graph\"\n}\n```\n"
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              example: '[this request has a binary response]'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not-found'
        '429':
          $ref: '#/components/responses/too-many-requests'
        '500':
          $ref: '#/components/responses/internal-server-error'
  /api/v2/graphs/cypher:
    parameters:
    - $ref: '#/components/parameters/header.prefer'
    post:
      operationId: RunCypherQuery
      summary: Run a cypher query
      description: Runs a manual cypher query directly against the database.
      tags:
      - Cypher
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                include_properties:
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/model.unified-graph.graph.w.property.keys'
        '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.
    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.
    unsupported-media-type:
      description: '**Unsupported Media Type**

        Content-Type does not match expected formats.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api.error-wrapper'
          example:
            http_status: 415
            timestamp: '2024-02-19T19:27:43.866Z'
            request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            errors:
            - context: clients
              message: 'invalid content-type: [application/incorrect]; Content type must be application/json or application/zip'
    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.
    model.unified-graph.edge:
      type: object
      properties:
        source:
          type: string
        target:
          type: string
        label:
          type: string
        kind:
          type: string
        lastSeen:
          type: string
          format: date-time
        properties:
          type: object
          additionalProperties:
            type: object
    model.unified-graph.node:
      type: object
      properties:
        label:
          type: string
        kind:
          type: string
        kinds:
          type: array
          items:
            type: string
        objectId:
          type: string
        isTierZero:
          type: boolean
        isOwnedObject:
          type: boolean
        lastSeen:
          type: string
          format: date-time
        properties:
          type: object
          additionalProperties:
            type: object
    model.components.uuid:
      type: object
      properties:
        id:
          type: string
          format: uuid
          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.saved-queries-permissions.response:
      type: object
      properties:
        shared_to_user_ids:
          type: array
          items:
            $ref: '#/components/schemas/model.components.uuid'
        query_id:
          type: integer
          format: int64
        public:
          type: boolean
    model.components.int64.id:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: This is the unique identifier for this object.
    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.saved-query:
      allOf:
      - $ref: '#/components/schemas/model.components.int64.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          user_id:
            type: string
            format: uuid
            readOnly: true
          name:
            type: string
          query:
            type: string
          description:
            type: string
    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.saved-queries-permissions:
      allOf:
      - $ref: '#/components/schemas/model.components.int64.id'
      - $ref: '#/components/schemas/model.components.timestamps'
      - type: object
        properties:
          shared_to_user_id:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/null.uuid'
          query_id:
            type: integer
            format: int64
          public:
            type: boolean
    model.unified-graph.graph.w.property.keys:
      type: object
      properties:
        node_keys:
          type: array
          items:
            type: string
        edge_keys:
          type: array
          items:
            type: string
        nodes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/model.unified-graph.node'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/model.unified-graph.edge'
        literals:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type:
                - object
                - 'null'
                anyOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                - type: object
    api.params.query.skip:
      type: integer
      minimum: 0
      description: The number of items to skip in a paginated response.
    null.uuid:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        valid:
          description: Valid is true if `uuid` is not `null`.
          type: boolean
    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
  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