# Flowg8 · Dokument-Upload reservieren

Fordere eine fünfminütige Upload-Berechtigung für eine unveränderliche Datei an.

Erfordert runs:start oder Antragstellerzugang und Idempotency-Key. Flow-Version muss veröffentlicht und Dokumentfeld/Typ/Größe konfiguriert sein. Lade die echten Dateibytes per PUT auf upload.url und sende alle upload.headers exakt. Sende keinen Flowg8-Token an S3. Die Upload-Berechtigung gewährt keinen Lesezugriff. SHA-256 ist kleingeschriebenes Hex über die exakten Dateibytes; S3 prüft die signierte Prüfsumme und ein bedingter Schreibzugriff verhindert Überschreiben. Die Wiederholung derselben Reservierung kann ihre temporäre Upload-URL erneuern.

## 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: Rolle requester erforderlich. 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