# Flowg8 · Reserve a document upload

Request a five-minute upload capability for one immutable file.

Requires runs:start or requester access and Idempotency-Key. Flow version must be published and document field/type/size configured. PUT the actual file bytes to upload.url, sending every upload.headers value exactly. Do not send your Flowg8 token to S3. Upload capability does not grant read access. SHA-256 is lowercase hexadecimal over the exact file bytes; S3 validates the signed checksum and a conditional write prevents overwrites. Retrying the same reservation may refresh its transient upload URL.

## POST /v1/documents/uploads

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- flowVersionId (string, required): uuid
- fieldKey (string, required): 
- fileName (string, required): min length 1 · max length 180
- contentType (string, required): application/pdf | image/png | image/jpeg | application/vnd.openxmlformats-officedocument.wordprocessingml.document
- size (integer, required): min 1 · max 26214400
- sha256 (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/documents/uploads" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-document-upload-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "flowVersionId": "10000000-0000-4000-8000-000000000003",
  "fieldKey": "contract",
  "fileName": "contract.pdf",
  "contentType": "application/pdf",
  "size": 1234,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
```

## Response excerpt

```json
{
  "document": {
    "id": "10000000-0000-4000-8000-000000000012",
    "status": "uploading"
  },
  "upload": {
    "url": "https://private-bucket.s3.eu-central-1.amazonaws.com/<temporary-upload-capability>",
    "headers": {
      "content-type": "application/pdf",
      "x-amz-checksum-sha256": "<base64 checksum>",
      "if-none-match": "*"
    },
    "expiresAt": "2026-10-18T12:05:00.000Z"
  }
}
```

Source: /docs/document-upload
Full schemas: /docs/openapi.json