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:

Reserve — Tell SignStack you want to upload a file:
```
POST /v1/orgs/{orgId}/files/upload-url
{
  "file": {
    "name": "contract.pdf",
    "contentType": "application/pdf",
    "hash": "<SHA-256 hash>"
  }
}
```
Response: { "id": "f_01jv8m7qfj6xj9gkz7a4s2h8e", "name": "contract.pdf", "uploadUrl": "https://storage.googleapis.com/..." }
Upload — PUT the file's bytes directly to the uploadUrl. It's pre-authorized — don't attach an Authorization header, and set Content-Type to the value you sent in the request.
Confirm — SignStack marks the file as Available once the upload completes and the hash (if provided) matches.

file.hash is the file's SHA-256 (hex) — optional but recommended; supplying it enables dedup and later integrity verification. id is an opaque identifier — don't parse it. Once available, reference the file by id anywhere (asset content, brand logos, signing envelopes). To upload more than one file, repeat the call.

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

Fetch a file's metadata plus a freshly-signed download URL:

GET /v1/orgs/{orgId}/files/{fileId}

The response includes a short-lived downloadUrl for direct cloud download. If it expires, call the endpoint again for a fresh one.

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

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

The Workflow Engine (Steps)

Namespaces