Evidence Library

Drata's Evidence Library serves as a repository for all the evidence you need to collect across your controls. The help docs have more information.

List Evidence Library Items

Find Evidence Library Items by search terms and filters.

🔒 Requires Evidence Library: List Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number
query Parameters
cursor
string

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

size
number [ 1 .. 50 ]
Default: 20

Number of results to return

sort
string (SortTypeLimitedEnum)

Which field to sort by

Enum: "createdAt" "updatedAt"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
expand[]
Array of strings (EvidenceLibraryExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "user" "controls" "renewalSchemaAndVersions"
name
string <= 191 characters

Filter Evidence Library Items by name

Example: name=Evidence 1
statuses[]
Array of strings (EvidenceStatusEnum)

Filter Evidence Library Items by statuses

Items Enum: "READY" "EXPIRING_SOON" "EXPIRED" "NEEDS_SOURCE" "NEEDS_ATTENTION"
Responses
200

Successful

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

get/workspaces/{workspaceId}/evidence-library
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "name": "Security Policy Document",
      • "description": "This document outlines our security policies and procedures.",
      • "implementationGuidance": "Follow the company security training guidelines and ensure all employees complete the training within 30 days of onboarding.",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "user": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        },
      • "versions": [],
      • "renewalSchema": {
        • "renewalDate": "2020-07-06",
        • "renewalScheduleType": "ONE_YEAR"
        },
      • "controls": [
        • {
          • "id": 1,
          • "code": "AC-1",
          • "name": "Access Control",
          • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n predetermined criteria. Incidents are escalated per policy.",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}

Create Evidence Library Item

Create a new Evidence Library Item.

🔒 Requires Evidence Library: Create Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

Request Body schema:
required
name
required
string <= 191 characters

Evidence Library Item name

description
string or null <= 30000 characters

Evidence Library Item description

implementationGuidance
string or null <= 30000 characters

Implementation guidance for this Evidence Library Item

renewalDate
string or null <date>

Evidence renewal date. Required only when renewalScheduleType is CUSTOM or not provided. If renewalScheduleType is provided (other than CUSTOM), this date will be calculated automatically.

renewalScheduleType
required
string

Evidence renewal schedule type. When provided (except CUSTOM), the renewal date will be calculated automatically from today. Use CUSTOM to set a specific renewal date.

Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"
file
string <binary>

Evidence file. Accepted file extensions: .pdf, .docx, .odt, .xlsx, .ods, .pptx, .odp, .gif, .jpeg, .jpg, .png

base64File
string

JSON string with evidence file in Base64 format (alternative to file upload)

filedAt
required
string <date>

The date when the evidence was originally filed/created

ownerId
number

User ID of the Evidence Library Item owner

url
string <uri> <= 768 characters

URL to the evidence

controlIds
Array of numbers or null

List of control IDs to associate with this Evidence Library Item

ticketUrl
string or null

Ticket provider URL (for ticket-based evidence)

Responses
201

Created

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

post/workspaces/{workspaceId}/evidence-library
Request samples
No sample
Response samples
application/json
{
  • "id": 1,
  • "name": "Security Policy Document",
  • "description": "This document outlines our security policies and procedures.",
  • "implementationGuidance": "Follow the company security training guidelines and ensure all employees complete the training within 30 days of onboarding.",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "versions": [],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "controls": [
    • {
      • "id": 1,
      • "code": "AC-1",
      • "name": "Access Control",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n predetermined criteria. Incidents are escalated per policy.",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}

Get Evidence Library Item

Get a specific Evidence Library Item by ID.

🔒 Requires Evidence Library: List Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number
evidenceLibraryId
required
number
query Parameters
expand[]
Array of strings (EvidenceLibraryExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "user" "controls" "renewalSchemaAndVersions"
Responses
200

Successful

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

get/workspaces/{workspaceId}/evidence-library/{evidenceLibraryId}
Request samples
Response samples
application/json
{
  • "id": 1,
  • "name": "Security Policy Document",
  • "description": "This document outlines our security policies and procedures.",
  • "implementationGuidance": "Follow the company security training guidelines and ensure all employees complete the training within 30 days of onboarding.",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "versions": [],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "controls": [
    • {
      • "id": 1,
      • "code": "AC-1",
      • "name": "Access Control",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n predetermined criteria. Incidents are escalated per policy.",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}

Update Evidence Library Item

Update an existing Evidence Library Item.

🔒 Requires Evidence Library: Update Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number
evidenceLibraryId
required
number
Request Body schema:
required
name
string <= 191 characters

Evidence name

description
string or null <= 30000 characters

Evidence description

implementationGuidance
string or null <= 30000 characters

Implementation guidance for this Evidence Library Item

filedAt
string <date>

The date when the Evidence was originally filed/created. Required when file, base64File, url, or ticketUrl is provided.

renewalDate
string or null <date>

Evidence renewal date. Required only when renewalScheduleType is CUSTOM. If renewalScheduleType is provided (other than CUSTOM), this date will be calculated automatically.

renewalScheduleType
string or null

Evidence renewal schedule type. When provided (except CUSTOM), the renewal date will be calculated automatically from today. Use CUSTOM to set a specific renewal date. Required when renewalDate is provided or when content is provided.

Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"
file
string <binary>

Evidence file. Accepted file extensions: .pdf, .docx, .odt, .xlsx, .ods, .pptx, .odp, .gif, .jpeg, .jpg, .png

base64File
string

JSON string with Evidence file in Base64 format (alternative to file upload)

url
string or null <uri> <= 768 characters

URL to the Evidence

ownerId
number

User ID of the Evidence Library Item owner

controlIds
Array of numbers or null

List of control IDs to associate with this Evidence

ticketUrl
string or null

Ticket provider URL (for ticket-based Evidence)

Responses
200

Successful

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

put/workspaces/{workspaceId}/evidence-library/{evidenceLibraryId}
Request samples
No sample
Response samples
application/json
{
  • "id": 1,
  • "name": "Security Policy Document",
  • "description": "This document outlines our security policies and procedures.",
  • "implementationGuidance": "Follow the company security training guidelines and ensure all employees complete the training within 30 days of onboarding.",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "versions": [],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "controls": [
    • {
      • "id": 1,
      • "code": "AC-1",
      • "name": "Access Control",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n predetermined criteria. Incidents are escalated per policy.",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}

Delete Evidence Library Item

Delete an Evidence Library Item.

🔒 Requires Evidence Library: Delete Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number
evidenceLibraryId
required
number
Responses
200
204

No Content

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

delete/workspaces/{workspaceId}/evidence-library/{evidenceLibraryId}
Request samples
Response samples
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}