openapi: 3.1.0
info:
  title: Drata Public API v2
  version: "2.0.0"
  description: >-
    Best-effort OpenAPI for Drata's Public REST API v2, used to manage assets,
    personnel, controls, frameworks, evidence, policies, vendors, tasks, audits,
    risks, and monitoring tests for SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR and
    other compliance programs.
  contact:
    name: API Evangelist
    email: kin@apievangelist.com
    url: https://developers.drata.com/openapi/reference/v2/overview/
servers:
  - url: https://public-api.drata.com/public/v2
    description: Drata Public API v2
security:
  - bearerAuth: []
tags:
  - name: Assets
  - name: Personnel
  - name: Controls
  - name: Frameworks
  - name: Policies
  - name: Vendors
  - name: Tasks
  - name: Audits
  - name: Risks
  - name: Evidence Library
  - name: Monitoring Tests
paths:
  /assets:
    get:
      tags: [Assets]
      summary: Find assets by search terms and filters
      operationId: listAssets
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 25 }
      responses:
        "200": { description: A page of assets }
    post:
      tags: [Assets]
      summary: Manually add a new asset to the account
      operationId: createAsset
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Asset" }
      responses:
        "201": { description: Asset created }
  /assets/{assetId}:
    parameters:
      - name: assetId
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Assets]
      summary: Retrieve an asset
      operationId: getAsset
      responses:
        "200": { description: Asset details }
    put:
      tags: [Assets]
      summary: Update asset properties
      operationId: updateAsset
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Asset" }
      responses:
        "200": { description: Asset updated }
    delete:
      tags: [Assets]
      summary: Remove a virtual or manually added asset
      operationId: deleteAsset
      responses:
        "204": { description: Asset removed }
  /personnel:
    get:
      tags: [Personnel]
      summary: List personnel
      operationId: listPersonnel
      responses:
        "200": { description: A page of personnel records }
    post:
      tags: [Personnel]
      summary: Create personnel
      operationId: createPersonnel
      responses:
        "201": { description: Personnel created }
  /personnel/{personnelId}:
    parameters:
      - name: personnelId
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Personnel]
      summary: Get personnel
      operationId: getPersonnel
      responses:
        "200": { description: Personnel record }
    put:
      tags: [Personnel]
      summary: Update personnel
      operationId: updatePersonnel
      responses:
        "200": { description: Personnel updated }
    delete:
      tags: [Personnel]
      summary: Delete personnel
      operationId: deletePersonnel
      responses:
        "204": { description: Personnel removed }
  /controls:
    get:
      tags: [Controls]
      summary: List controls
      operationId: listControls
      responses:
        "200": { description: A page of controls }
  /controls/{controlId}:
    parameters:
      - name: controlId
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Controls]
      summary: Get a control
      operationId: getControl
      responses:
        "200": { description: Control details }
  /frameworks:
    get:
      tags: [Frameworks]
      summary: List frameworks (SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR, etc.)
      operationId: listFrameworks
      responses:
        "200": { description: A page of frameworks }
  /policies:
    get:
      tags: [Policies]
      summary: List policies
      operationId: listPolicies
      responses:
        "200": { description: A page of policies }
  /vendors:
    get:
      tags: [Vendors]
      summary: List vendors
      operationId: listVendors
      responses:
        "200": { description: A page of vendors }
    post:
      tags: [Vendors]
      summary: Create a vendor
      operationId: createVendor
      responses:
        "201": { description: Vendor created }
  /tasks:
    get:
      tags: [Tasks]
      summary: List tasks
      operationId: listTasks
      responses:
        "200": { description: A page of tasks }
  /audits:
    get:
      tags: [Audits]
      summary: List audits
      operationId: listAudits
      responses:
        "200": { description: A page of audits }
  /risks:
    get:
      tags: [Risks]
      summary: List risks in the risk register
      operationId: listRisks
      responses:
        "200": { description: A page of risks }
  /evidence-library:
    get:
      tags: [Evidence Library]
      summary: List evidence in the evidence library
      operationId: listEvidence
      responses:
        "200": { description: A page of evidence items }
  /monitoring-tests:
    get:
      tags: [Monitoring Tests]
      summary: List monitoring tests
      operationId: listMonitoringTests
      responses:
        "200": { description: A page of monitoring tests }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Asset:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        owner: { type: string }