Evidence

Evidence items hold one or more artifacts, the files, URLs, or ticket references that demonstrate a control is operating.
Use the evidence-files endpoint to pre-upload a file, then reference the returned fileKey when creating or updating an Evidence item.

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,
            • "artifactName": "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. Provide the binary as either a multipart file or a Base64-encoded base64File; exactly one is required. 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> 
Artifact source as a file. Provide exactly one of file or base64File. 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


 
base64File
string
Artifact source as a Base64-encoded file in data URL format (alternative to file). Provide exactly one of file or base64File.


 
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,
        • "artifactName": "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"
      }
    ]
}
Delete Evidence
Permanently delete an Evidence item and all of its artifacts. To delete a single artifact and leave the Evidence item in place, use the delete artifact endpoint.


🔒 Requires Evidence Library: Delete Evidence permission.


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


 
evidenceId
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/{evidenceId}
Request samples 
Response samples 
application/json
{
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}
List Evidence Artifacts
List the artifacts of a single evidence item. Returns one entry per artifact, not one per artifact version, so each id is stable across replacements and is the ID accepted by the other artifact endpoints.


🔒 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
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"  
name
string  <= 191 characters 
Filter artifacts by name (prefix match)


 
 Example:  name=Q4-2024-Security-Audit
artifactTypes[]
Array of strings (ArtifactType) 
Filter artifacts by type


Items Enum: "URL" "S3_FILE" "TICKET_PROVIDER" "NONE" "GOOGLE_DRIVE" "ONE_DRIVE" "BOX" "DROPBOX" "SHARE_POINT" "TEST_RESULT"  
isArchived
boolean
True returns only archived (past) artifacts, false only active ones. Omit to return both.


 
 Example:  isArchived=false
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}/artifacts
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "artifactName": "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"
      }
    ],
  • "pagination": {
    • "cursor": "string"
    }
}
Update Evidence Artifact
Partially update an existing artifact's artifactName and/or filedAt in place on its current version. To replace the artifact's actual source (file/URL/ticket), use replaceArtifacts on the update Evidence endpoint instead.


🔒 Requires Evidence Library: Update Evidence permission.


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


 
evidenceId
required
number
 
artifactId
required
number
 
Request Body schema: application/json
required
artifactName
string or null  <= 191 characters 
Custom name for the artifact. Omit to leave unchanged; send null to clear it.


 
filedAt
string or null
The date when the artifact was filed/effective. Omit to leave unchanged; send null to clear it.


 
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}/artifacts/{artifactId}
Request samples 
application/json
{
  • "artifactName": "Q4 Security Review",
  • "filedAt": "2020-07-06"
}
Response samples 
application/json
{
  • "id": 1,
  • "artifactName": "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"
}
Delete Evidence Artifact
Permanently delete a single artifact from an evidence item, including its full version history. To move an artifact to past artifacts instead, pass its ID in pastArtifacts on the update Evidence endpoint.


🔒 Requires Evidence Library: Delete Evidence permission.


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


 
evidenceId
required
number
 
artifactId
required
number
 
Responses 
204
No Content


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


delete/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts/{artifactId}
Request samples 
Response samples 
application/json
{
  • "name": "string",
  • "statusCode": 0,
  • "message": "string",
  • "code": 0,
  • "debugInfo": {
    • "name": "string",
    • "message": "string",
    • "stack": "string"
    }
}
Perform Evidence Artifact Action
Archive an artifact (move it to past artifacts) or restore it (move it back to current artifacts). Both are reversible and leave the version history intact.


🔒 Requires Evidence Library: Update Evidence permission.


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


 
evidenceId
required
number
 
artifactId
required
number
 
Request Body schema: application/json
required
action
required
string
Action to execute: archive moves the artifact to past artifacts, restore moves it back to current artifacts. Both are reversible; to remove an artifact and its version history permanently, use the delete artifact endpoint instead.


 Enum: "archive" "restore"  
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


post/workspaces/{workspaceId}/evidence/{evidenceId}/artifacts/{artifactId}/actions
Request samples 
application/json
{
  • "action": "archive"
}
Response samples 
application/json
{
  • "id": 1,
  • "artifactName": "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"
}