Get Presigned URL

Get an S3 presigned URL for uploading large documents

POST /api/validate_stream_presigned_url

Get Presigned URL

cURL

curl --request POST \
  --url https://api.example.com/api/validate_stream_presigned_url/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_category": "<string>",
  "document_metadata": {},
  "content_type": "<string>",
  "filename": "<string>"
}
'

200 OK

{
  "job_id": "abc123def456",
  "upload_url": "https://zerodrift-ai-v1-validation-documents-dev.s3.amazonaws.com/documents/abc123def456.bin?X-Amz-Algorithm=...",
  "upload_method": "PUT",
  "s3_bucket": "zerodrift-ai-v1-validation-documents-dev",
  "s3_key": "documents/abc123def456.bin",
  "expires_at": "2026-01-08T11:30:00Z",
  "expires_in_seconds": 3600,
  "content_type": "application/pdf",
  "required_headers": {
    "Content-Type": "application/pdf",
    "x-amz-meta-job_id": "abc123def456",
    "x-amz-meta-uploaded_at": "2026-01-08T10:30:00",
    "x-amz-meta-filename": "my_document.pdf",
    "x-amz-meta-document_category": "retail_investor_letter"
  },
  "instructions": {
    "step_1": "Upload your document to the upload_url using HTTP PUT with ALL required_headers",
    "step_2": "After successful upload, call POST /api/validate_stream_start/ with the job_id to start validation",
    "note": "You MUST include all required_headers exactly as provided or S3 will return SignatureDoesNotMatch",
    "example_curl": "curl -X PUT \"<upload_url>\" -H \"Content-Type: application/pdf\" -H \"x-amz-meta-job_id: abc123...\" ... --data-binary @your-document.pdf"
  }
}

Get an S3 presigned URL for uploading large documents (recommended for files > 6MB).

Request Body

document_category · string

Document category. Required if document_metadata is not provided.

document_metadata · object

Detailed metadata for precise rule matching. Required if document_category is not provided.

content_type · string · default: "application/octet-stream"

MIME type of the document

filename · string

Original filename for reference

Response

job_id · string

Unique identifier for the validation job

upload_url · string

S3 presigned URL for file upload

upload_method · string

HTTP method to use for upload (always “PUT”)

s3_bucket · string

S3 bucket name

s3_key · string

S3 object key

expires_at · string

ISO 8601 timestamp when the URL expires

expires_in_seconds · integer

Seconds until URL expiration

content_type · string

The content type to use when uploading

required_headers · object

Important: All headers that MUST be included in the upload request. The presigned URL is signed with these headers, so omitting any will result in a SignatureDoesNotMatch error from S3.

instructions · object

Step-by-step instructions and example curl command for uploading

200 OK

{
  "job_id": "abc123def456",
  "upload_url": "https://zerodrift-ai-v1-validation-documents-dev.s3.amazonaws.com/documents/abc123def456.bin?X-Amz-Algorithm=...",
  "upload_method": "PUT",
  "s3_bucket": "zerodrift-ai-v1-validation-documents-dev",
  "s3_key": "documents/abc123def456.bin",
  "expires_at": "2026-01-08T11:30:00Z",
  "expires_in_seconds": 3600,
  "content_type": "application/pdf",
  "required_headers": {
    "Content-Type": "application/pdf",
    "x-amz-meta-job_id": "abc123def456",
    "x-amz-meta-uploaded_at": "2026-01-08T10:30:00",
    "x-amz-meta-filename": "my_document.pdf",
    "x-amz-meta-document_category": "retail_investor_letter"
  },
  "instructions": {
    "step_1": "Upload your document to the upload_url using HTTP PUT with ALL required_headers",
    "step_2": "After successful upload, call POST /api/validate_stream_start/ with the job_id to start validation",
    "note": "You MUST include all required_headers exactly as provided or S3 will return SignatureDoesNotMatch",
    "example_curl": "curl -X PUT \"<upload_url>\" -H \"Content-Type: application/pdf\" -H \"x-amz-meta-job_id: abc123...\" ... --data-binary @your-document.pdf"
  }
}

Required Headers: The presigned URL is signed with metadata headers. You must include ALL headers from the required_headers field exactly as provided when uploading your file. Missing or incorrect headers will result in a SignatureDoesNotMatch error from S3.

Example

cURL

# Step 1: Get presigned URL
RESPONSE=$(curl -s -X POST "https://zhshgjat2b.execute-api.us-east-1.amazonaws.com/dev/v1/api/validate_stream_presigned_url/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_category": "retail_investor_letter",
    "content_type": "application/pdf",
    "filename": "my_document.pdf"
  }')

# Extract values from response
UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload_url')
JOB_ID=$(echo $RESPONSE | jq -r '.job_id')

# Step 2: Upload file with ALL required headers
# IMPORTANT: Include every header from required_headers or you'll get SignatureDoesNotMatch
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  -H "x-amz-meta-job_id: $JOB_ID" \
  -H "x-amz-meta-uploaded_at: $(echo $RESPONSE | jq -r '.required_headers["x-amz-meta-uploaded_at"]')" \
  -H "x-amz-meta-filename: my_document.pdf" \
  -H "x-amz-meta-document_category: retail_investor_letter" \
  --data-binary @my_document.pdf

echo "Job ID: $JOB_ID"