Evidence Library

Find evidence by workspace id

List evidence given the provided 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
page
number >= 1
Default: 1

Which page of data are you requesting

limit
number [ 1 .. 50 ]
Default: 20

How many items are you requesting

q
string or null

Filter data to search term

Example: q=Evidence 1
fileKey
string <= 191 characters

Drata S3 file key

Example: fileKey=UUID-FOLDER/reports/UUID-FOLDER/TestReport.pdf
sort
string

Which type of sort (default: RENEWAL_DATE)

Enum: "DATE" "CREATED_AT" "DESCRIPTION" "RENEWAL_DATE" "NAME" "USER" "STATUS" "EVIDENCE_TYPE"
Example: sort=RENEWAL_DATE
sortDir
string

Which direction to sort the data (default: ASC)

Enum: "ASC" "DESC"
Example: sortDir=ASC
excludeIds
Array of numbers

Evidence ids to exclude from the results

excludeControlId
number

Exclude policies if mapped to control id

Example: excludeControlId=1
status
Array of strings

Status for the evidence

Items Enum: "READY" "EXPIRING_SOON" "EXPIRED" "NEEDS_SOURCE" "NEEDS_ATTENTION"
Example: status=EXPIRED&status=READY
versionSourceTypes[]
Array of strings

This value represents the “Source Type” of the current version of this evidence.

Items Enum: "FILE" "URL" "TICKET" "TEST"
Example: versionSourceTypes[]=FILE
Responses
200
400

Malformed data and/or validation errors

401

Invalid Authorization

402

You must upgrade your plan to use this feature

403

You are not allowed to perform this action

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 training",
      • "description": "Security Training completed evidence test",
      • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "user": {
        • "id": 1,
        • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "jobTitle": "CEO",
        • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
        • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        },
      • "controls": [
        • {
          • "id": "123",
          • "name": "Databases Monitored and Alarmed",
          • "code": "DCF-1002",
          • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on predetermined criteria. Incidents are escalated per policy.",
          • "question": "Does the organization implement tools to monitor its databases and notify appropriate personnel of incidents based on predetermined criteria?",
          • "activity": "1. Ensure tools are implemented to monitor databases             2. Ensure notifications based on specific criteria are sent to the appropriate personnel             3. Escalate incidents appropriately",
          • "slug": "databases-monitored-and-alarmed",
          • "archivedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "renewalSchema": {
        • "renewalDate": "2020-07-06",
        • "renewalScheduleType": "ONE_YEAR"
        },
      • "isExpired": false,
      • "versions": []
      }
    ],
  • "page": 1,
  • "limit": 10,
  • "total": 100
}
Add evidence by workspace id
Add evidence


🔒 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 
Document name


 
description
string or null  <= 30000 characters 
Library document description


 
renewalDate
required
string
Library document renewal date


 
renewalScheduleType
required
string
Library Document renewal schedule type


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
file
string <binary> 
Accepted file extensions: .pdf, .docx, .odt, .doc, .xlsx, .ods, .pptx, .odp, .gif, .jpg, .jpeg, .png, .json, .csv, .md, .markdown, .txt, .zip


 
base64File
string
JSON string with external evidence in Base64 format.


 
source
required
string
The type of evidence


 Enum: "URL" "S3_FILE" "TICKET_PROVIDER" "NONE" "GOOGLE_DRIVE" "ONE_DRIVE" "BOX" "DROPBOX" "SHARE_POINT" "TEST_RESULT"  
url
string or null <uri>   <= 768 characters 
The url to the evidence


 
filedAt
required
string
The date in which the evidence was originally filed/created


 
ownerId
required
number
Owner id


 
controlIds
Array of numbers or null
List of control IDs


 
ticketUrl
string or null
Ticket provider url


 
Responses 
201
Created


400
Malformed data and/or validation errors


401
Invalid Authorization


402
You must upgrade your plan to use this feature


403
You are not allowed to perform this action


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


413
The file was too large to upload


500
Internal server error


503
Third party system was unavailable


post/workspaces/{workspaceId}/evidence-library
Request samples 
No sample
Response samples 
application/json
{
  • "id": 1,
  • "name": "Security training",
  • "description": "Security Training completed evidence test",
  • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "jobTitle": "CEO",
    • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
    • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "controls": [
    • {
      • "id": "123",
      • "name": "Databases Monitored and Alarmed",
      • "code": "DCF-1002",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on predetermined criteria. Incidents are escalated per policy.",
      • "question": "Does the organization implement tools to monitor its databases and notify appropriate personnel of incidents based on predetermined criteria?",
      • "activity": "1. Ensure tools are implemented to monitor databases             2. Ensure notifications based on specific criteria are sent to the appropriate personnel             3. Escalate incidents appropriately",
      • "slug": "databases-monitored-and-alarmed",
      • "archivedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "isExpired": false,
  • "versions": []
}
Find Evidence by its ID and workspace ID
Get Evidence details


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


 
Responses 
200
400
Malformed data and/or validation errors


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/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "name": "Security training",
  • "description": "Security Training completed evidence test",
  • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "jobTitle": "CEO",
    • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
    • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "controls": [
    • {
      • "id": "123",
      • "name": "Databases Monitored and Alarmed",
      • "code": "DCF-1002",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on predetermined criteria. Incidents are escalated per policy.",
      • "question": "Does the organization implement tools to monitor its databases and notify appropriate personnel of incidents based on predetermined criteria?",
      • "activity": "1. Ensure tools are implemented to monitor databases             2. Ensure notifications based on specific criteria are sent to the appropriate personnel             3. Escalate incidents appropriately",
      • "slug": "databases-monitored-and-alarmed",
      • "archivedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "isExpired": false,
  • "versions": []
}
Update evidence by evidence id and workspace id
Update Evidence metadata


🔒 Requires Evidence Library: Update Evidence permission.


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


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


 
description
string or null  <= 30000 characters 
Library document description


 
renewalDate
required
string
Library document renewal date


 
renewalScheduleType
required
string
Library Document renewal schedule type


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
file
string <binary> 
Accepted file extensions: .pdf, .docx, .odt, .doc, .xlsx, .ods, .pptx, .odp, .gif, .jpg, .jpeg, .png, .json, .csv, .md, .markdown, .txt, .zip


 
base64File
string
JSON string with external evidence in Base64 format.


 
source
required
string
The type of evidence


 Enum: "URL" "S3_FILE" "TICKET_PROVIDER" "NONE" "GOOGLE_DRIVE" "ONE_DRIVE" "BOX" "DROPBOX" "SHARE_POINT" "TEST_RESULT"  
url
string or null <uri>   <= 768 characters 
The url to the evidence


 
filedAt
required
string
The date in which the evidence was originally filed/created


 
ownerId
required
number
Owner id


 
controlIds
Array of numbers or null
List of control IDs


 
ticketUrl
string or null
Ticket provider url


 
Responses 
200
400
Malformed data and/or validation errors


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/{id}
Request samples 
No sample
Response samples 
application/json
{
  • "id": 1,
  • "name": "Security training",
  • "description": "Security Training completed evidence test",
  • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "user": {
    • "id": 1,
    • "entryId": "aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "jobTitle": "CEO",
    • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
    • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "controls": [
    • {
      • "id": "123",
      • "name": "Databases Monitored and Alarmed",
      • "code": "DCF-1002",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on predetermined criteria. Incidents are escalated per policy.",
      • "question": "Does the organization implement tools to monitor its databases and notify appropriate personnel of incidents based on predetermined criteria?",
      • "activity": "1. Ensure tools are implemented to monitor databases             2. Ensure notifications based on specific criteria are sent to the appropriate personnel             3. Escalate incidents appropriately",
      • "slug": "databases-monitored-and-alarmed",
      • "archivedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "renewalSchema": {
    • "renewalDate": "2020-07-06",
    • "renewalScheduleType": "ONE_YEAR"
    },
  • "isExpired": false,
  • "versions": []
}
Remove a piece of evidence by evidence id and workspace id
Delete a piece of evidence.


🔒 Requires Evidence Library: Delete Evidence permission.


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


 
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


delete/workspaces/{workspaceId}/evidence-library/{id}
Request samples 
Response samples 
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}
Generate Evidence download URL
Generates a pre-signed download URL for an Evidence file


🔒 Requires Evidence Library: List Evidence permission.


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


 
Responses 
200
Successful


400
Malformed data and/or validation errors


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/{evidenceId}/version/{versionId}/download
Request samples 
Response samples 
application/json
{}
Update evidence sync by evidence id and workspace id
Update evidence sync


🔒 Requires Evidence Library: Update Evidence permission.


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


 
Request Body schema: application/json
required
safeBaseSyncStatus
required
string
The SafeBase sync status of the document


 Enum: "NOT_SYNCED" "PENDING" "COMPLETE" "ERROR"  
safeBaseDocumentId
string or null
The Safebase document ID


 
Responses 
200
400
Malformed data and/or validation errors


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/sync/{id}
Request samples 
application/json
{
  • "safeBaseSyncStatus": "COMPLETE",
  • "safeBaseDocumentId": "1234"
}
Response samples 
application/json
{
  • "id": 1
}