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.
Note: these are the legacy single-artifact endpoints; new integrations should use the Evidence endpoints.

List Evidence Library Items

Superseded by GET /workspaces/{workspaceId}/evidence. Find Evidence Library Items by search terms and filters.

🔒 Requires Evidence Library: List Evidence permission.

Securitybearer
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

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 .. 500 ]
Default: 50

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"
includeTotalCount
boolean
Default: false

Include total count of all matching records in response. Only honored on first page (when cursor is null).

Example: includeTotalCount=false
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: "NEEDS_ARTIFACT" "ERROR" "READY" "EXPIRING_SOON" "EXPIRED" "NEEDS_SOURCE" "NEEDS_ATTENTION"
Responses
200

Successful

401

Invalid Authorization

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.",
      • "evidenceTemplateCode": "REQ-12",
      • "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": {
        • "id": 1,
        • "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",
    • "totalCount": 0
    }
}
Create Evidence Library Item
Superseded by POST /workspaces/{workspaceId}/evidence. 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


 
base64File
string
Artifact source as Base64-encoded file. When provided, renewalScheduleType, filedAt, and ownerId are required. Only one artifact source (file, base64File, url, ticketUrl, or fileKey) can be provided. JSON string with artifact file in Base64 format (alternative to file upload).


 
controlIds
Array of numbers or null
List of control IDs to associate with this Evidence Library Item


 
description
string or null  <= 30000 characters 
Evidence Library Item description


 
filedAt
string <date> 
The date when the artifact was originally filed/created. Required when an artifact source is provided (file, base64File, url, ticketUrl, or fileKey).


 
file
string <binary> 
Artifact source as file. When provided, renewalScheduleType, filedAt, and ownerId are required. Only one artifact source (file, base64File, url, ticketUrl, or fileKey) can be provided. Accepted file extensions: .pdf, .docx, .odt, .doc, .xlsx, .ods, .pptx, .odp, .gif, .jpg, .jpeg, .png, .json, .csv, .md, .markdown, .txt, .html, .log, .zip, .msg, .mp4


 
fileKey
string
Artifact source as a pre-uploaded S3 file key, obtained from the presigned POST /upload-urls endpoint (purpose: evidence). When provided, renewalScheduleType, filedAt, and ownerId are required. Only one artifact source (file, base64File, url, ticketUrl, or fileKey) can be provided.


 
implementationGuidance
string or null  <= 30000 characters 
Implementation guidance for this Evidence Library Item


 
ownerId
number
User ID of the Evidence Library Item owner. Required when an artifact source is provided (file, base64File, url, ticketUrl, or fileKey).


 
renewalDate
string or null <date> 
Artifact renewal date. Required only when renewalScheduleType is CUSTOM. When renewalScheduleType is provided (other than CUSTOM), this date will be calculated automatically from filedAt.


 
renewalScheduleType
string
Artifact renewal schedule type. Required when adding new artifact (file, base64File, url, ticketUrl, or fileKey). When provided (except CUSTOM), the renewal date will be calculated automatically from filedAt. Use CUSTOM to set a specific renewal date via the renewalDate field.


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
ticketUrl
string or null <uri> 
Artifact source as ticket URL. When provided, renewalScheduleType, filedAt, and ownerId are required. Only one artifact source (file, base64File, url, ticketUrl, or fileKey) can be provided.


 
url
string <uri>   <= 768 characters 
Artifact source as URL. When provided, renewalScheduleType, filedAt, and ownerId are required. Only one artifact source (file, base64File, url, ticketUrl, or fileKey) can be provided.


 
Responses 
201
Created


401
Invalid Authorization


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.",
  • "evidenceTemplateCode": "REQ-12",
  • "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": {
    • "id": 1,
    • "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
Superseded by GET /workspaces/{workspaceId}/evidence/{evidenceId}. Get a specific Evidence Library Item by ID.


🔒 Requires Evidence Library: List Evidence permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
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


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.",
  • "evidenceTemplateCode": "REQ-12",
  • "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": {
    • "id": 1,
    • "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
Superseded by PUT /workspaces/{workspaceId}/evidence/{evidenceId}. Update an existing Evidence Library Item.


🔒 Requires Evidence Library: Update Evidence permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
evidenceLibraryId
required
number
 
Request Body schema: 
required
base64File
string
Artifact source as Base64-encoded file. When provided, this adds new artifact to the Evidence Library Item, making filedAt, renewalScheduleType,renewalDate (if renewalScheduleType is CUSTOM), and ownerId (if not already assigned) required. Only one artifact source (file, base64File, url, or ticketUrl) can be provided. JSON string with artifact file in Base64 format (alternative to file upload).


 
controlIds
Array of numbers or null
List of control IDs to associate with this Evidence Library Item. Passing any value (including an empty array) will override existing controlIds. Omit this field to leave existing associations unchanged.


 
description
string or null  <= 30000 characters 
Evidence Library Item description


 
filedAt
string <date> 
The date when the artifact was originally filed/created. Required when adding new artifact (file, base64File, url, or ticketUrl). Optional when updating the creation date of an existing artifact.


 
file
string <binary> 
Artifact source as File. When provided, this adds new artifact to the Evidence Library Item, making filedAt, renewalScheduleType, renewalDate (if renewalScheduleType is CUSTOM), and ownerId (if not already assigned) required. Only one artifact source (file, base64File, url, or ticketUrl) can be provided.Accepted file extensions: .pdf, .docx, .odt, .doc, .xlsx, .ods, .pptx, .odp, .gif, .jpg, .jpeg, .png, .json, .csv, .md, .markdown, .txt, .html, .log, .zip, .msg, .mp4


 
implementationGuidance
string or null  <= 30000 characters 
Implementation guidance for this Evidence Library Item


 
name
string  <= 191 characters 
Evidence Library Item name


 
ownerId
number
User ID of the Evidence Library Item owner. Can be updated independently at any time. Also required when adding new artifact (file, base64File, url, or ticketUrl) if the Evidence Library Item does not already have an owner assigned.


 
renewalDate
string or null <date> 
Artifact renewal date. Required when renewalScheduleType is CUSTOM. Optional when updating the renewal date of an existing artifact. When renewalScheduleType is provided (other than CUSTOM), this date will be calculated automatically from filedAt.


 
renewalScheduleType
string or null
Artifact renewal schedule type. Required when adding new artifact (file, base64File, url, or ticketUrl). Optional when updating the renewal schedule of an existing artifact. When provided (except CUSTOM), the renewal date will be calculated automatically from filedAt. Use CUSTOM to set a specific renewal date via the renewalDate field.


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
ticketUrl
string or null <uri> 
Artifact source as ticket URL. When provided, this adds new artifact to the Evidence Library Item, making filedAt, renewalScheduleType, and ownerId (if not already assigned) required. Only one artifact source (file, base64File, url, or ticketUrl) can be provided.


 
url
string or null <uri>   <= 768 characters 
Artifact source as URL. When provided, this adds new artifact to the Evidence Library Item, making filedAt, renewalScheduleType, renewalDate (if renewalScheduleType is CUSTOM), and ownerId (if not already assigned) required. Only one artifact source (file, base64File, url, or ticketUrl) can be provided.


 
Responses 
200
Successful


401
Invalid Authorization


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.",
  • "evidenceTemplateCode": "REQ-12",
  • "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": {
    • "id": 1,
    • "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
The Workspace ID associated to the Account


 
evidenceLibraryId
required
number
 
Responses 
204
No Content


401
Invalid Authorization


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"
    }
}
Get Evidence Library Version
Superseded by GET /workspaces/{workspaceId}/evidence/{evidenceId} with expand[]=artifacts. Retrieve Evidence Library Version details.


🔒 Requires Evidence Library: List Evidence permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
evidenceLibraryId
required
number
 
versionId
required
number
 
query Parameters
expand[]
Array of strings (EvidenceLibraryVersionExpandEnum) 
List of subcollections and sub-objects to expand


Items Value: "downloadUrl"  
Responses 
200
Successful


401
Invalid Authorization


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}/versions/{versionId}
Request samples 
Response samples 
application/json
{}