Uploads let you request a pre-signed S3 URL to upload a file for a given purpose (e.g. Evidence), then reference the resulting object key when creating the associated resource.
Request Upload URL
Generate a pre-signed S3 URL to upload a file for the given purpose. PUT the file directly to presignedUrl with a Content-Type header matching the contentType sent in this request (or the auto-derived type if omitted), then use the returned objectKey per the semantics of that purpose.
🔒 Requires Evidence Library: Create Evidence permission.
Securitybearer
Request
Request Body schema: application/json
required
purpose
required
string
What the uploaded file will be attached to. Determines authorization, storage prefix, and workspace requirements.
Value:"evidence"
workspaceId
number
Required when purpose is workspace-scoped (currently: evidence). Omit for account-global purposes.
fileName
string <= 191 characters
The original filename of the file that will be uploaded. When provided, it is used to build the human-readable segment of the S3 object key. Optional for browser-driven uploads (includeWebUploadUrl: true) where the user picks the file after the URL is minted — in that case the actual filename lands on the evidence artifact once the browser PUT completes.
contentType
string
The MIME type of the file being uploaded. When provided, sent back as the Content-Type on the pre-signed URL, so the client's PUT must send a matching Content-Type header. When omitted, the URL is signed WITHOUT binding a Content-Type — the client can PUT any mime (useful for browser flows where the mime is not known at mint time).
includeWebUploadUrl
boolean
When true, the response additionally includes a webUploadUrl — a short-lived, browser-facing URL that hosts a drag-and-drop upload page backed by this pre-signed URL. Intended for surfaces (e.g., MCP tools in Claude Desktop) that want to hand the user a clickable link rather than a curl command. Defaults to false.
existingArtifactId
number
When set, the browser upload session is bound as a REPLACE of the referenced artifact. When the user completes the upload, the API bumps the existing artifact chain (same artifact ID, new version, previous version archived) instead of creating a new artifact. If the user abandons the upload, no changes to the evidence occur -- the previous version stays current. Validated at mint time to ensure the artifact exists, belongs to the caller, and is a current S3_FILE. Only meaningful with includeWebUploadUrl: true (browser flow).
addToEvidenceId
number
When set, the browser upload session is bound as an ADD of a new artifact to the referenced evidence. When the user completes the upload, the API attaches a new S3_FILE artifact to the evidence -- no artifact row is created at mint time. If the user abandons the upload, no artifact appears on the evidence (no phantom placeholder). Validated at mint time to ensure the evidence exists and belongs to the workspace. Mutually exclusive with existingArtifactId. Only meaningful with includeWebUploadUrl: true (browser flow).
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