Downloading Files - SuperAI Flows

When SuperAI Flows processes documents, task outputs often include file references as gs:// URLs. These point to files stored in Google Cloud Storage, but you don’t need to understand GCS internals — the File API handles everything. Example gs:// URL in a task output:

{
  "document_url": "gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2"
}

Prerequisites

curl — for making HTTP requests
jq — for parsing JSON in shell scripts (optional, but recommended)
A SuperAI Flows API key — get one from the dashboard under Settings → API Keys

Quick start

Download a file in one command:

curl -f -L -H "X-API-Key: saf_your_api_key" \
  "https://flows.super.ai/api/files/download?uri=gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2" \
  -o downloaded_file.pdf

The -L flag tells curl to follow the redirect to the actual download URL.
The -f flag makes curl fail with an error instead of saving error responses as your file.

Authentication

Both file endpoints require authentication. You can use either method:

Method	Header	Example
API Key (recommended)	`X-API-Key`	`X-API-Key: saf_abc123...`
JWT Token	`Authorization`	`Authorization: Bearer eyJhbGci...`

About API keys:

API keys start with the saf_ prefix (e.g., saf_org_550e8400_abc123...).
Get your API key from the dashboard under Settings → API Keys.
Store keys in environment variables — never hardcode them in scripts.

About JWT tokens: obtained by authenticating with your email and password. See the API Quickstart. Tokens expire after 1 hour and must be refreshed.

Two ways to download

Option 1: Direct download (GET)

Use GET /api/files/download for the simplest approach. This endpoint redirects you to a temporary signed URL.

curl -f -L -H "X-API-Key: $SAF_API_KEY" \
  "https://flows.super.ai/api/files/download?uri=gs://bucket/path/to/file" \
  -o output_file.pdf

If your URI contains special characters, URL-encode it first:

ENCODED_URI=$(printf '%s' "$GS_URL" | jq -sRr @uri)
curl -f -L -H "X-API-Key: $SAF_API_KEY" \
  "https://flows.super.ai/api/files/download?uri=$ENCODED_URI" -o file.pdf

Parameter	Required	Description
`uri`	Yes	The `gs://` URL from your task output (URL-encoded)
`redirect`	No	Set to `false` to get JSON instead of a redirect (default: `true`)

Response: 302 redirect to a pre-signed download URL (valid for 1 hour).

Option 2: Resolve URL first (POST)

Use POST /api/files/resolve when you need the download URL for further processing or want to keep URIs out of server logs.

curl -X POST "https://flows.super.ai/api/files/resolve" \
  -H "X-API-Key: $SAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uri": "gs://bucket/path/to/file"}'

{
  "download_url": "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=...",
  "expires_at": "2025-01-15T15:00:00+00:00",
  "expires_in_seconds": 3600
}

Then download using the returned URL:

curl -o output_file.pdf "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=..."

Complete example: download after flow completion

This script executes a flow, waits for completion, and downloads any output files:

#!/bin/bash
set -e

# Configuration — use environment variables for API key
API_KEY="${SAF_API_KEY:-saf_your_api_key}"
FLOW_ID="your-flow-id"
BASE_URL="https://flows.super.ai"
MAX_ATTEMPTS=60  # 5 minutes timeout (60 * 5 seconds)

# 1. Create flow execution
echo "Starting flow execution..."
EXEC_RESPONSE=$(curl -s -X POST "$BASE_URL/api/flow-executions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"flow_id\": \"$FLOW_ID\",
    \"input\": {
      \"filename\": \"invoice.pdf\",
      \"mime_type\": \"application/pdf\",
      \"document_url\": \"https://cdn.super.ai/invoice-example.pdf\"
    }
  }")

EXEC_ID=$(echo "$EXEC_RESPONSE" | jq -r .id)
if [ "$EXEC_ID" = "null" ] || [ -z "$EXEC_ID" ]; then
  echo "Failed to create execution. Response: $EXEC_RESPONSE"
  exit 1
fi
echo "Execution started: $EXEC_ID"

# 2. Wait for completion
ATTEMPT=0
while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
  STATUS=$(curl -s "$BASE_URL/api/flow-executions/$EXEC_ID" \
    -H "X-API-Key: $API_KEY" | jq -r .status)
  echo "Status: $STATUS (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)"

  if [ "$STATUS" = "completed" ]; then break
  elif [ "$STATUS" = "failed" ]; then echo "Execution failed!"; exit 1; fi

  ATTEMPT=$((ATTEMPT + 1))
  sleep 5
done

# 3. Get task outputs
RESULTS=$(curl -s "$BASE_URL/api/task-executions?flow_execution_id=$EXEC_ID" \
  -H "X-API-Key: $API_KEY")

# 4. Download any gs:// URLs from the output (requires jq)
echo "$RESULTS" | jq -r '.. | select(type == "string" and startswith("gs://"))' 2>/dev/null | while read -r GS_URL; do
  if [ -n "$GS_URL" ]; then
    FILENAME=$(basename "$GS_URL")
    ENCODED_URI=$(printf '%s' "$GS_URL" | jq -sRr @uri)
    if curl -f -L -H "X-API-Key: $API_KEY" \
      "$BASE_URL/api/files/download?uri=$ENCODED_URI" -o "$FILENAME"; then
      echo "Downloaded: $FILENAME"
    else
      echo "Failed to download: $FILENAME"
    fi
  fi
done

echo "Done!"

Error handling

Status	Description	Common causes
400	Bad Request	URI doesn’t start with `gs://`, malformed URI, path traversal attempt
401	Unauthorized	Missing or invalid API key / token
403	Forbidden	File belongs to a different organization, invalid bucket
404	Not Found	Flow doesn’t exist, you lack access, or the file was deleted from storage
500	Server Error	Internal error generating download URL

Example error response:

{
  "error": {
    "message": "Access denied: you do not have access to this file",
    "code": "forbidden"
  },
  "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
}

Include the request_id when contacting support for faster resolution.

Always use -f -L with curl on the GET endpoint: -L follows the redirect to the actual download URL, and -f makes curl return a non-zero exit code on HTTP 4xx/5xx errors instead of silently saving an error response as your output file.

Security

Organization-scoped access — You can only download files from flows your organization owns.
Temporary URLs — Pre-signed download URLs expire after 1 hour.
Path validation — The API rejects path traversal attempts.
Bucket validation — Only files from the authorized storage bucket can be accessed.

For sensitive files, prefer POST /api/files/resolve to keep URIs out of server access logs.

FAQ

What URI formats are supported?

Currently only gs:// URIs (Google Cloud Storage) are supported.

How long are download URLs valid?

Pre-signed URLs are valid for 1 hour. Request a new URL if your download fails after this time.

Can I download files from any flow?

No. You can only download files from flows that belong to your organization.

Do I need to parse the gs:// URL?

No — pass the full URI exactly as received from the task output.

Which endpoint should I use?

Use GET /api/files/download for simple downloads with curl. Use POST /api/files/resolve when you need the URL for programmatic use or want to keep URIs out of logs.

Need help? Email support@super.ai and include your request_id and flow ID.

​Prerequisites

​Quick start

​Authentication

​Two ways to download

​Option 1: Direct download (GET)

​Option 2: Resolve URL first (POST)

​Complete example: download after flow completion

​Error handling

​Security

​FAQ

Prerequisites

Quick start

Authentication

Two ways to download

Option 1: Direct download (GET)

Option 2: Resolve URL first (POST)

Complete example: download after flow completion

Error handling

Security

FAQ