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.",
          • "isReady": true,
          • "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.",
      • "isReady": true,
      • "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.",
      • "isReady": true,
      • "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.",
      • "isReady": true,
      • "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"
    }
}