Skip to main content

Get Storage Upload URL

GET 
/api/v1/assets/new/content_storage_url

Get a pre-signed URL for uploading a file directly to cloud storage (S3). The returned URL and signing fields allow the client to POST the file to S3 without routing file bytes through the FileSpin API server.

This is a three-step upload flow:

  1. Get storage URL — Call this endpoint with the filename parameter. The response contains a pre-signed S3 POST URL, signing fields, and an asset_id.
  2. Upload to S3 — POST the file as multipart/form-data to the returned storage.url, including all storage.fields as form fields and the file as the file field.
  3. Register the asset — Call POST /api/v1/assets/new/register_asset with the asset_id, file size, checksum, and upload timestamps to register the asset in FileSpin and trigger processing.

When to use this endpoint​

Use this endpoint when you need to upload files from a client that can POST directly to S3 (e.g., the FileSpin File Picker widget, Teleport, or a custom uploader). For simpler server-side uploads, use the standard Upload Asset endpoint instead.

Pre-signed URL expiry​

The returned URL is valid for 24 hours (expiry: 86400 seconds). After expiry, you must request a new URL.

Example response​

{
  "asset_id": "ec279822540b412e903827f473bb53a3",
  "storage": {
    "name": "photo.jpg",
    "url": "https://my-bucket.s3.amazonaws.com/",
    "fields": {
      "key": "originals/ec279822540b412e903827f473bb53a3/original/original__photo.jpg",
      "x-amz-algorithm": "AWS4-HMAC-SHA256",
      "x-amz-credential": "AKIA.../20240515/eu-west-2/s3/aws4_request",
      "x-amz-date": "20240515T154302Z",
      "policy": "eyJleHBpcmF0aW9uIjog...",
      "x-amz-signature": "cc47e86f1353..."
    },
    "protocol": "POST",
    "expiry": 86400,
    "key": "/originals/ec279822540b412e903827f473bb53a3/original/original__photo.jpg",
    "bucket": "my-bucket",
    "storage_type": "AMAZON_S3"
  }
}

Uploading to S3​

Use the storage.url and storage.fields to construct a multipart POST request to S3:

curl -X POST "https://my-bucket.s3.amazonaws.com/" \
  -F "key=originals/ec279822.../original/original__photo.jpg" \
  -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
  -F "x-amz-credential=AKIA.../20240515/eu-west-2/s3/aws4_request" \
  -F "x-amz-date=20240515T154302Z" \
  -F "policy=eyJleHBpcmF0aW9uIjog..." \
  -F "x-amz-signature=cc47e86f1353..." \
  -F "file=@photo.jpg"

Registering the asset​

After a successful S3 upload, register the asset so FileSpin can begin processing:

curl -X POST "https://app.filespin.io/api/v1/assets/new/register_asset" \
  -H "X-FileSpin-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "ec279822540b412e903827f473bb53a3",
    "size": 1048576,
    "checksum": "d41d8cd98f00b204e9800998ecf8427e",
    "upload_time": "2024-05-15T15:43:02Z",
    "upload_started_at": "2024-05-15T15:43:00Z",
    "upload_completed_at": "2024-05-15T15:43:02Z",
    "service_data": {
      "app": "MyApp",
      "build": "1.0.0",
      "deployment_data": {
        "client": "WebUploader",
        "location": "LONDON"
      },
      "network_bandwidth": 50
    }
  }'

Request​

Responses​

Pre-signed upload URL generated successfully