File Management

SignStack stores binary files — PDFs and images — in cloud storage and references them by a unique, permanent fileId. Text content (HTML/Handlebars and CSS) lives inline on the asset itself.

How It Works

API (Direct Upload)

SignStack uses pre-signed URLs for direct client-to-cloud transfers:

1. Initiate — Tell SignStack you want to upload:

   POST /v1/orgs/{orgId}/files/initiate-upload
   { "fileName": "contract.pdf", "contentHash": "<SHA-256 hash>" }
   

   plaintext

   Response: { "fileId": "file_abc123", "signedUrl": "https://storage.googleapis.com/..." }

2. Upload — PUT the file directly to the signed URL.

3. Confirm — SignStack marks the file as Available once the upload completes and the hash matches.

Studio

File handling is automatic. In the asset editor, just pick a PDF or image — Studio runs the upload flow under the hood (initiate-upload, direct-to-cloud transfer, asset creation with the resulting fileId).

CLI

When you push from the CLI, file management is automatic:

# Push uploads all referenced binary files and creates resources
signstack push

The CLI reads your asset YAML, finds the local files referenced by spec.file (e.g. file: ./files/nda_form.pdf), uses the same upload flow, and creates the resources.

Downloads

Request a signed download URL for any file:

GET /v1/orgs/{orgId}/files/{fileId}/signed-url

The response includes a short-lived URL for direct cloud download.

Benefits

• Fast and reliable — Direct client-to-cloud transfer ensures speedy, reliable file uploads and downloads.
• Stable references — Use fileId everywhere, regardless of storage backend
• Integrity — SHA-256 hashing ensures end-to-end data integrity
• Security — Short-lived, permission-scoped signed URLs

Related Concepts

• Assets — Binary assets (PDF, image) reference uploaded files via spec.file (CLI) or spec.fileId (API); HTML and CSS assets store content inline