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

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
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
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
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
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
{}
List Evidence Items
List evidence items with pagination, filtering, and optional expand.


🔒 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"  
expand[]
Array of strings (EvidenceExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "owners" "artifacts" "controls"  
name
string  <= 191 characters 
Filter evidence items by name (prefix match)


 
 Example:  name=SOC2 Evidence
ownerIds[]
Array of numbers
IDs of the users that own the evidence current version.


 
 Example:  ownerIds[]=1&ownerIds[]=2&ownerIds[]=3
frameworkIds[]
Array of numbers
Array of Ids of frameworks to be used as filters


 
 Example:  frameworkIds[]=1&frameworkIds[]=2&frameworkIds[]=3
evidenceStatuses[]
Array of strings (ComputedEvidenceStatusEnum) 
Filter evidence items by statuses


Items Enum: "NEEDS_ARTIFACT" "EXPIRED" "EXPIRING_SOON" "TEST_ERROR" "TEST_FAILED" "READY" "TEST_PASSED" "TEST_UNUSED" "TEST_DISABLED" "TEST_DELETED"  
artifactTypes[]
Array of strings (ArtifactTypeEnum) 
Filter evidence items by artifact types


Items Enum: "URL" "S3_FILE" "TICKET_PROVIDER" "NONE" "GOOGLE_DRIVE" "ONE_DRIVE" "BOX" "DROPBOX" "SHARE_POINT" "TEST_RESULT"  
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
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",
      • "renewalDate": "2020-07-06",
      • "renewalScheduleType": "ONE_YEAR",
      • "status": "READY",
      • "safeBaseSyncStatus": "COMPLETE",
      • "owners": {
        • "data": [
          • {
            • "id": 1,
            • "email": "[email protected]",
            • "firstName": "Sally",
            • "lastName": "Smith",
            • "createdAt": "2025-07-01T16:45:55.246Z",
            • "updatedAt": "2025-07-01T16:45:55.246Z"
            }
          ],
        • "totalCount": 15
        },
      • "artifacts": {
        • "data": [
          • {
            • "id": 1,
            • "name": "Q4-2024-Security-Audit.pdf",
            • "extension": "pdf",
            • "artifactVersion": 1,
            • "source": "https://example.com/evidence/document.pdf",
            • "artifactSafeBasesyncStatus": "COMPLETE",
            • "artifactType": "S3_FILE",
            • "filedAt": "2025-07-01T16:45:55.246Z",
            • "archivedAt": "2025-07-01T16:45:55.246Z",
            • "createdAt": "2025-07-01T16:45:55.246Z"
            }
          ],
        • "totalCount": 15
        },
      • "controls": {
        • "data": [
          • {
            • "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"
            }
          ],
        • "totalCount": 15
        }
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Create Evidence
Create a new Evidence item with one or more artifacts. File artifacts must be pre-uploaded via the evidence-files endpoint and referenced by fileKey.


🔒 Requires Evidence Library: Create Evidence permission.


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


 
Request Body schema: application/json
required
name
required
string  <= 191 characters 
Evidence name


 
description
string or null  <= 30000 characters 
Evidence description


 
implementationGuidance
string or null  <= 30000 characters 
Guidance for implementing evidence


 
stepsToReproduce
string or null  <= 30000 characters 
Steps to reproduce or collect this evidence


 
required
Array of objects (EvidenceArtifactRequestPublicV2Dto) 
Array of artifacts to create for this evidence. Each artifact should reference a pre-uploaded file (via fileKey) or a URL.


 
ownerId
number
Owner user ID


 
controlIds
Array of numbers or null
List of control IDs to link to this evidence


 
renewalDate
string or null
Evidence renewal date. Optional - if not provided and renewalScheduleType is set, it may be auto-calculated by the backend based on the schedule type.


 
renewalScheduleType
string or null
Evidence renewal schedule type


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
Responses 
201
Created


400
Malformed data and/or validation errors


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
Request samples 
application/json
{
  • "name": "Security Training",
  • "description": "Security Training completed evidence",
  • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
  • "stepsToReproduce": "Steps to reproduce the issue or evidence collection process",
  • "artifacts": [
    • {
      • "type": "S3_FILE",
      • "artifactName": "Security Policy v2.pdf",
      • "fileKey": "123/evidence-library/62545abd-5469-4a19-abc2-55df8809b225/policy.pdf",
      • "filedAt": "2020-07-06"
      },
    • {}
    ],
  • "ownerId": 1,
  • "controlIds": [
    • 1,
    • 2,
    • 3
    ],
  • "renewalDate": "2020-07-06",
  • "renewalScheduleType": "ONE_YEAR"
}
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",
  • "renewalDate": "2020-07-06",
  • "renewalScheduleType": "ONE_YEAR",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "artifactsRequested": 3,
  • "artifactsCreated": 2,
  • "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"
      }
    ],
  • "linkedWorkspaces": [
    • {
      • "id": 1,
      • "name": "Drata"
      }
    ],
  • "artifacts": [
    • {
      • "id": 1,
      • "source": "document.pdf",
      • "artifactName": "document.pdf",
      • "type": "S3_FILE",
      • "artifactVersion": 1,
      • "filedAt": "2020-07-06",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "metadata": {
        • "originalFileName": "security-policy.pdf",
        • "mimeType": "application/pdf",
        • "extension": "pdf"
        },
      • "ticketUrl": "string"
      }
    ]
}
Upload Evidence Artifact File
Pre-upload a file to be used as an evidence artifact. Returns a fileKey that can be referenced in the create/update Evidence endpoints.


🔒 Requires Evidence Library: Create Evidence permission.


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


 
Request Body schema: multipart/form-data
required
file
string <binary> 
 
Responses 
201
Created


400
Malformed data and/or validation errors


401
Invalid Authorization


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


post/workspaces/{workspaceId}/evidence-files
Request samples 
Response samples 
application/json
{
  • "fileKey": "account-id/evidence-library/uuid/file.pdf",
  • "originalFilename": "My Security Training (v2).pdf",
  • "mimeType": "application/pdf",
  • "fileSize": 1024
}
Get Evidence Item
Get a specific evidence item by ID with optional expand.


🔒 Requires Evidence Library: List Evidence permission.


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


 
evidenceId
required
number
 
query Parameters
expand[]
Array of strings (EvidenceExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "owners" "artifacts" "controls"  
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/{evidenceId}
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",
  • "renewalDate": "2020-07-06",
  • "renewalScheduleType": "ONE_YEAR",
  • "status": "READY",
  • "safeBaseSyncStatus": "COMPLETE",
  • "owners": {
    • "data": [
      • {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        }
      ],
    • "totalCount": 15
    },
  • "artifacts": {
    • "data": [
      • {
        • "id": 1,
        • "name": "Q4-2024-Security-Audit.pdf",
        • "extension": "pdf",
        • "artifactVersion": 1,
        • "source": "https://example.com/evidence/document.pdf",
        • "artifactSafeBasesyncStatus": "COMPLETE",
        • "artifactType": "S3_FILE",
        • "filedAt": "2025-07-01T16:45:55.246Z",
        • "archivedAt": "2025-07-01T16:45:55.246Z",
        • "createdAt": "2025-07-01T16:45:55.246Z"
        }
      ],
    • "totalCount": 15
    },
  • "controls": {
    • "data": [
      • {
        • "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"
        }
      ],
    • "totalCount": 15
    }
}
Update Evidence
Update an existing Evidence item. Supports multi-artifact operations: add new artifacts, archive artifacts (past), restore artifacts (current), and replace artifacts.


🔒 Requires Evidence Library: Update Evidence permission.


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


 
evidenceId
required
number
 
Request Body schema: application/json
required
name
string  <= 191 characters 
Evidence name


 
description
string or null  <= 30000 characters 
Evidence description


 
implementationGuidance
string or null  <= 30000 characters 
Guidance for implementing evidence. Partial-update: omit to leave the current value unchanged; send null to clear it.


 
stepsToReproduce
string or null  <= 30000 characters 
Steps to reproduce or collect this evidence. Partial-update: omit to leave the current value unchanged; send null to clear it.


 
renewalDate
string or null
Renewal date (ISO 8601 format, required if renewalScheduleType is not NONE)


 
renewalScheduleType
string or null
Renewal schedule type for the evidence


 Enum: "ONE_MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "ONE_YEAR" "CUSTOM" "NONE"  
ownerId
number
Evidence owner user ID


 
controlIds
Array of numbers or null
List of control IDs to link (additions only, cannot remove existing links)


 
Array of objects (EvidenceArtifactAddRequestPublicV2Dto) 
New artifacts to add to the evidence


 
pastArtifacts
Array of numbers or null
List of artifact IDs to archive (move to past)


 
currentArtifacts
Array of numbers or null
List of artifact IDs to restore (move to current)


 
Array of objects (EvidenceArtifactReplaceRequestPublicV2Dto) 
Artifacts to replace by adding a new version to an existing artifact chain. Preserves the artifact ID across versions.


 
Responses 
200
Successful


400
Malformed data and/or validation errors


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/{evidenceId}
Request samples 
application/json
{
  • "name": "Updated Security Training",
  • "description": "Security Training completed evidence",
  • "implementationGuidance": "Example of architectural diagram www.drata/arch-diagram-example.com",
  • "stepsToReproduce": "Steps to reproduce the issue or evidence collection process",
  • "renewalDate": "2020-07-06",
  • "renewalScheduleType": "ONE_YEAR",
  • "ownerId": 789,
  • "controlIds": [
    • 101,
    • 102
    ],
  • "newArtifacts": [],
  • "pastArtifacts": [
    • 1,
    • 2
    ],
  • "currentArtifacts": [
    • 3
    ],
  • "replaceArtifacts": []
}
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",
  • "renewalDate": "2020-07-06",
  • "renewalScheduleType": "ONE_YEAR",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "artifactsRequested": 3,
  • "artifactsCreated": 2,
  • "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"
      }
    ],
  • "linkedWorkspaces": [
    • {
      • "id": 1,
      • "name": "Drata"
      }
    ],
  • "artifacts": [
    • {
      • "id": 1,
      • "source": "document.pdf",
      • "artifactName": "document.pdf",
      • "type": "S3_FILE",
      • "artifactVersion": 1,
      • "filedAt": "2020-07-06",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "metadata": {
        • "originalFileName": "security-policy.pdf",
        • "mimeType": "application/pdf",
        • "extension": "pdf"
        },
      • "ticketUrl": "string"
      }
    ]
}