Get Upload Strategy (Direct or Presigned URL)

curl --request POST \
  --url https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filename": "profile-photo.jpg",
  "contentType": "image/jpeg",
  "size": 102400
}
'

import requests

url = "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy"

payload = {
    "filename": "profile-photo.jpg",
    "contentType": "image/jpeg",
    "size": 102400
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filename: 'profile-photo.jpg', contentType: 'image/jpeg', size: 102400})
};

fetch('https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => 'profile-photo.jpg',
    'contentType' => 'image/jpeg',
    'size' => 102400
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy"

	payload := strings.NewReader("{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}"

response = http.request(request)
puts response.read_body

{
  "method": "presigned",
  "uploadUrl": "https://s3-bucket.amazonaws.com/",
  "fields": {
    "bucket": "my-s3-bucket",
    "key": "app-key/avatars/profile-photo.jpg",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "AKIA.../20250905/us-east-2/s3/aws4_request",
    "X-Amz-Date": "20250905T000000Z",
    "Policy": "eyJ...",
    "X-Amz-Signature": "abc123..."
  },
  "key": "profile-photo.jpg",
  "confirmRequired": true,
  "confirmUrl": "/api/storage/buckets/avatars/objects/profile-photo.jpg/confirm-upload",
  "expiresAt": "2025-09-05T01:00:00Z"
}

Client

Get Upload Strategy (Direct or Presigned URL)

Returns the upload strategy for the requested object. Local storage always returns direct upload endpoints. S3 storage may return either presigned or direct strategies depending on the S3_USE_PRESIGNED_URLS configuration. Clients must determine the upload flow from the returned response, using the method field, rather than assuming behavior based on the configured storage backend.

The filename is used verbatim as the object key. Uploading to an existing key replaces the current object in place. To upload with a server-generated unique key instead, use POST /api/storage/buckets/{bucketName}/objects. End-user creates and replacements are gated by the storage.objects row-level-security policies.

POST

api

storage

buckets

{bucketName}

upload-strategy

Get Upload Strategy (Direct or Presigned URL)

curl --request POST \
  --url https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filename": "profile-photo.jpg",
  "contentType": "image/jpeg",
  "size": 102400
}
'

import requests

url = "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy"

payload = {
    "filename": "profile-photo.jpg",
    "contentType": "image/jpeg",
    "size": 102400
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filename: 'profile-photo.jpg', contentType: 'image/jpeg', size: 102400})
};

fetch('https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => 'profile-photo.jpg',
    'contentType' => 'image/jpeg',
    'size' => 102400
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy"

	payload := strings.NewReader("{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/storage/buckets/{bucketName}/upload-strategy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"profile-photo.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"size\": 102400\n}"

response = http.request(request)
puts response.read_body

{
  "method": "presigned",
  "uploadUrl": "https://s3-bucket.amazonaws.com/",
  "fields": {
    "bucket": "my-s3-bucket",
    "key": "app-key/avatars/profile-photo.jpg",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "AKIA.../20250905/us-east-2/s3/aws4_request",
    "X-Amz-Date": "20250905T000000Z",
    "Policy": "eyJ...",
    "X-Amz-Signature": "abc123..."
  },
  "key": "profile-photo.jpg",
  "confirmRequired": true,
  "confirmUrl": "/api/storage/buckets/avatars/objects/profile-photo.jpg/confirm-upload",
  "expiresAt": "2025-09-05T01:00:00Z"
}

Authorizations

x-api-key

string

header

required

Path Parameters

bucketName

string

required

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

filename

string

required

Object key to upload to (used verbatim)

Example:

"profile-photo.jpg"

contentType

string

MIME type of the file

Example:

"image/jpeg"

size

integer

File size in bytes

Example:

102400

Response

Upload strategy details

method

enum<string>

required

Upload method. presigned is returned when S3 presigned URLs are enabled; direct is returned for local storage and S3 proxy mode.

Available options:

presigned,

direct

Example:

"presigned"

uploadUrl

string

required

URL to upload the file to

Example:

"https://s3-bucket.amazonaws.com/"

key

string

required

Final logical object key (the filename, used verbatim).

Example:

"profile-photo.jpg"

confirmRequired

boolean

required

Whether the upload must be confirmed after completion. When false, clients must not call the confirm upload endpoint.

Example:

true

fields

object

Form fields for presigned POST (S3 only)

Example:

{
  "bucket": "my-s3-bucket",
  "key": "app-key/avatars/profile.jpg",
  "X-Amz-Algorithm": "AWS4-HMAC-SHA256"
}

confirmUrl

string

Upload confirmation endpoint. Present only when confirmRequired is true.

Example:

"/api/storage/buckets/avatars/objects/profile.jpg/confirm-upload"

expiresAt

string<date-time>

Expiration time for presigned URL (S3 only)

Example:

"2025-09-05T01:00:00Z"

⌘I

Tables

Schedules

Authentication

Records

Storage

Model Gateway

Functions

Realtime

Messaging

Payments

Secrets

Logs

Usage

Metadata

Health

Deployments

Dashboard

Get Upload Strategy (Direct or Presigned URL)

Authorizations

Path Parameters

Body

Response