Drata Custom Data Records API

openapi: 3.2.0
info:
  title: Drata Custom Data Records API
  version: V2
  contact: {}
  description: 'Operations tagged Custom Data Records across 2 of this provider''s published API definitions: drata-api-v2-openapi.json, drata-api-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public-api.drata.com/public/v2
- url: https://public-api.eu.drata.com/public/v2
- url: https://public-api.apac.drata.com/public/v2
tags:
- name: Custom Data Records
  description: Custom Data Records are JSON evidence records pushed to a Custom Connection resource. Use the session management endpoints to batch upload records and track the status of bulk operations. You can create monitors on this data to provide continuous compliance. The [help docs](https://help.drata.com/en/articles/11995676-part-1-custom-connections-and-tests) have more information.
paths:
  /custom-connections/{connectionId}/resources/{resourceId}/records:
    get:
      description: 'List Custom Data Records matching the provided filters.


        🔒 Requires **Custom Connections Management: List Custom Connections** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_listCustomDataRecords
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      - name: cursor
        required: false
        in: query
        description: This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a `pagination.cursor` value that can be used in the subsequent request to retrieve the next page of results
        schema:
          type: string
      - name: size
        required: false
        in: query
        description: Number of results to return
        schema:
          minimum: 1
          maximum: 500
          default: 50
          type: number
      - name: sort
        required: false
        in: query
        description: Which field to sort by
        schema:
          $ref: '#/components/schemas/SortTypeLimitedEnum'
      - name: sortDir
        required: false
        in: query
        description: The direction to sort the data
        schema:
          $ref: '#/components/schemas/SortDirectionEnum'
      - name: includeTotalCount
        required: false
        in: query
        description: Include total count of all matching records in response. Only honored on first page (when cursor is null).
        schema:
          default: false
          example: false
          type: boolean
      - name: sessionId
        required: false
        in: query
        description: Filter records by session ID.
        schema:
          minLength: 3
          maxLength: 64
          example: session-abc-123
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataRecordsResponsePublicV2Dto'
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: List Custom Data Records
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-get
      x-product-area:
      - CUSTOM_CONNECTIONS
    post:
      description: 'Create or update Custom Data records for a Custom Connection.


        🔒 Requires **Custom Connections Data: Create Custom Connection Data** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_createCustomData
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomDataRequestPublicV2Dto'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  title: Single Record Operation
                  description: Drata supports creating or updating a single record. The response provides detailed feedback on the operation's outcome.
                  properties:
                    id:
                      type: string
                      example: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt:
                      type: string
                      example: '2020-07-06 12:00:00.000000'
                    updatedAt:
                      type: string
                      example: '2020-07-06 13:00:00.000000'
                    statusCode:
                      type: number
                      example: 200
                    data:
                      type: object
                      description: Custom data information, reflects record sent on request
                      additionalProperties: true
                  example:
                    id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 13:00:00.000000'
                    statusCode: 200
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                - type: array
                  title: Bulk Operation
                  description: Drata supports bulk operations to create multiple records simultaneously. The response provides detailed feedback for each individual record operation.
                  items:
                    properties:
                      id:
                        type: string
                        example: fd52f04f-a030-44ea-a5af-40919194ab7e
                      createdAt:
                        type: string
                        example: '2020-07-06 12:00:00.000000'
                      updatedAt:
                        type: string
                        example: '2020-07-06 13:00:00.000000'
                      statusCode:
                        type: number
                        example: 200
                      data:
                        type: object
                        description: Custom data information, reflects record sent on request
                        additionalProperties: true
                      error:
                        type: object
                        properties:
                          message:
                            type: string
                            description: Error message
                            example: 'Schema validation failed for data: [{"":"must have required property ''name''"}]'
                          code:
                            type: number
                            description: Error code
                            example: 28022
                  example:
                  - id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 13:00:00.000000'
                    statusCode: 200
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                  - id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 12:00:00.000000'
                    statusCode: 201
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                  - statusCode: 400
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                    error:
                      error:
                        message: 'Schema validation failed for data: [{"":"must have required property ''name''"}]'
                        code: 28022
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: fd52f04f-a030-44ea-a5af-40919194ab7e
                  createdAt:
                    type: string
                    example: '2020-07-06 12:00:00.000000'
                  updatedAt:
                    type: string
                    example: '2020-07-06 13:00:00.000000'
                  statusCode:
                    type: number
                    example: 200
                  data:
                    type: object
                    description: Custom data information, reflects record sent on request
                    additionalProperties: true
                example:
                  id: fd52f04f-a030-44ea-a5af-40919194ab7e
                  createdAt: '2020-07-06 12:00:00.000000'
                  updatedAt: '2020-07-06 13:00:00.000000'
                  statusCode: 200
                  data:
                    YOUR: DATA
                    PROPERTIES:
                      WILL: BE_HERE
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: Upsert Custom Data Records
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-data-post
      x-product-area:
      - CUSTOM_CONNECTIONS
    servers:
    - url: https://public-api.drata.com/public/v2
    - url: https://public-api.eu.drata.com/public/v2
    - url: https://public-api.apac.drata.com/public/v2
  /custom-connections/{connectionId}/resources/{resourceId}/sessions:
    get:
      description: 'List Custom Data Sessions matching the provided filters.


        🔒 Requires **Custom Connections Management: List Custom Connections** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_listSessions
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      - name: cursor
        required: false
        in: query
        description: This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a `pagination.cursor` value that can be used in the subsequent request to retrieve the next page of results
        schema:
          type: string
      - name: size
        required: false
        in: query
        description: Number of results to return
        schema:
          minimum: 1
          maximum: 500
          default: 50
          type: number
      - name: sort
        required: false
        in: query
        description: Which field to sort by
        schema:
          $ref: '#/components/schemas/SortTypeLimitedEnum'
      - name: sortDir
        required: false
        in: query
        description: The direction to sort the data
        schema:
          $ref: '#/components/schemas/SortDirectionEnum'
      - name: includeTotalCount
        required: false
        in: query
        description: Include total count of all matching records in response. Only honored on first page (when cursor is null).
        schema:
          default: false
          example: false
          type: boolean
      - name: status
        required: false
        in: query
        description: Filter sessions by status
        schema:
          $ref: '#/components/schemas/CustomDataSessionStatusEnum'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionsResponsePublicV2Dto'
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: List Custom Data Sessions
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-get
      x-product-area:
      - CUSTOM_CONNECTIONS
    servers:
    - url: https://public-api.drata.com/public/v2
    - url: https://public-api.eu.drata.com/public/v2
    - url: https://public-api.apac.drata.com/public/v2
  /custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}:
    post:
      description: 'Insert or update Custom Data records in batches using Session Management.


        🔒 Requires **Custom Connections Data: Create Custom Connection Data** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_uploadSessionRecords
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      - name: sessionId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomDataSessionRequestPublicV2Dto'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  title: Single Record Operation
                  description: Drata supports creating or updating a single record. The response provides detailed feedback on the operation's outcome.
                  properties:
                    id:
                      type: string
                      example: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt:
                      type: string
                      example: '2020-07-06 12:00:00.000000'
                    updatedAt:
                      type: string
                      example: '2020-07-06 13:00:00.000000'
                    statusCode:
                      type: number
                      example: 200
                    data:
                      type: object
                      description: Custom data information, reflects record sent on request
                      additionalProperties: true
                  example:
                    id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 13:00:00.000000'
                    statusCode: 200
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                - type: array
                  title: Bulk Operation
                  description: Drata supports bulk operations to create multiple records simultaneously. The response provides detailed feedback for each individual record operation.
                  items:
                    properties:
                      id:
                        type: string
                        example: fd52f04f-a030-44ea-a5af-40919194ab7e
                      createdAt:
                        type: string
                        example: '2020-07-06 12:00:00.000000'
                      updatedAt:
                        type: string
                        example: '2020-07-06 13:00:00.000000'
                      statusCode:
                        type: number
                        example: 200
                      data:
                        type: object
                        description: Custom data information, reflects record sent on request
                        additionalProperties: true
                      error:
                        type: object
                        properties:
                          message:
                            type: string
                            description: Error message
                            example: 'Schema validation failed for data: [{"":"must have required property ''name''"}]'
                          code:
                            type: number
                            description: Error code
                            example: 28022
                  example:
                  - id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 13:00:00.000000'
                    statusCode: 200
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                  - id: fd52f04f-a030-44ea-a5af-40919194ab7e
                    createdAt: '2020-07-06 12:00:00.000000'
                    updatedAt: '2020-07-06 12:00:00.000000'
                    statusCode: 201
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                  - statusCode: 400
                    data:
                      YOUR: DATA
                      PROPERTIES:
                        WILL: BE_HERE
                    error:
                      error:
                        message: 'Schema validation failed for data: [{"":"must have required property ''name''"}]'
                        code: 28022
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: fd52f04f-a030-44ea-a5af-40919194ab7e
                  createdAt:
                    type: string
                    example: '2020-07-06 12:00:00.000000'
                  updatedAt:
                    type: string
                    example: '2020-07-06 13:00:00.000000'
                  statusCode:
                    type: number
                    example: 200
                  data:
                    type: object
                    description: Custom data information, reflects record sent on request
                    additionalProperties: true
                example:
                  id: fd52f04f-a030-44ea-a5af-40919194ab7e
                  createdAt: '2020-07-06 12:00:00.000000'
                  updatedAt: '2020-07-06 13:00:00.000000'
                  statusCode: 200
                  data:
                    YOUR: DATA
                    PROPERTIES:
                      WILL: BE_HERE
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: Upsert Custom Data Records with Session Management
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-data-post
      x-product-area:
      - CUSTOM_CONNECTIONS
    servers:
    - url: https://public-api.drata.com/public/v2
    - url: https://public-api.eu.drata.com/public/v2
    - url: https://public-api.apac.drata.com/public/v2
  /custom-connections/{connectionId}/resources/{resourceId}/sessions/{sessionId}/actions:
    post:
      description: 'Perform an action on a Custom Data record Session


        🔒 Requires **Custom Connections Data: Create Custom Connection Data** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_performSessionAction
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      - name: sessionId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionActionRequestPublicV2Dto'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionActionResponsePublicV2Dto'
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: Perform Session Action
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-data-post
      x-product-area:
      - CUSTOM_CONNECTIONS
    servers:
    - url: https://public-api.drata.com/public/v2
    - url: https://public-api.eu.drata.com/public/v2
    - url: https://public-api.apac.drata.com/public/v2
  /custom-connections/{connectionId}/resources/{resourceId}/records/{recordId}:
    put:
      description: 'Update an existing Custom Data record by ID.


        🔒 Requires **Custom Connections Data: Create and Update Custom Connection Data** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_updateCustomData
      parameters:
      - name: connectionId
        required: true
        in: path
        schema:
          type: number
      - name: resourceId
        required: true
        in: path
        schema:
          type: number
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomDataRequestPublicV2Dto'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataResponsePublicV2Dto'
        '400':
          description: Malformed data and/or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '401':
          description: Invalid Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '402':
          description: You must upgrade your plan to use this feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '403':
          description: You are not allowed to perform this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '412':
          description: You must accept the Drata terms and conditions to use the API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
        '413':
          description: The file was too large to upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponsePublicV2Dto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseDto'
      security:
      - bearer: []
      summary: Update Custom Data Record
      tags:
      - Custom Data Records
      x-drata-entitlement:
      - CUSTOM_CONNECTIONS_AND_TESTS
      x-drata-permissions:
      - custom-connections-data-put
      x-product-area:
      - CUSTOM_CONNECTIONS
    delete:
      description: 'Delete a Custom Data Record by ID.


        🔒 Requires **Custom Connections Data: Delete Custom Connection Data** permission.


        💎 Requires your account have the **Custom Connections and Tests** feature. Contact your CSM for help upgrading.'
      operationId: CustomDataRecordsPublicV2Controller_deleteCustomData
      parameters:
      - name: co

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/drata/refs/heads/main/openapi/drata-custom-data-records-api-openapi.yml