Upload File

curl --request POST \
  --url https://api.example.com/v1/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "folder": "<string>",
  "private": true,
  "expires": "<string>"
}
'

import requests

url = "https://api.example.com/v1/upload"

payload = {
    "folder": "<string>",
    "private": True,
    "expires": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({folder: '<string>', private: true, expires: '<string>'})
};

fetch('https://api.example.com/v1/upload', 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/v1/upload",
  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([
    'folder' => '<string>',
    'private' => true,
    'expires' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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/v1/upload"

	payload := strings.NewReader("{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}")

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

	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/v1/upload")
  .header("Content-Type", "application/json")
  .body("{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/upload")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "url": "<string>",
  "name": "<string>",
  "folder": "<string>",
  "size": 123,
  "type": "<string>",
  "private": true,
  "expires_at": "<string>",
  "created_at": "<string>"
}

POST

upload

Upload File

curl --request POST \
  --url https://api.example.com/v1/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "folder": "<string>",
  "private": true,
  "expires": "<string>"
}
'

import requests

url = "https://api.example.com/v1/upload"

payload = {
    "folder": "<string>",
    "private": True,
    "expires": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({folder: '<string>', private: true, expires: '<string>'})
};

fetch('https://api.example.com/v1/upload', 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/v1/upload",
  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([
    'folder' => '<string>',
    'private' => true,
    'expires' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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/v1/upload"

	payload := strings.NewReader("{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}")

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

	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/v1/upload")
  .header("Content-Type", "application/json")
  .body("{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/upload")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"folder\": \"<string>\",\n  \"private\": true,\n  \"expires\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "url": "<string>",
  "name": "<string>",
  "folder": "<string>",
  "size": 123,
  "type": "<string>",
  "private": true,
  "expires_at": "<string>",
  "created_at": "<string>"
}

Upload a file to StashFyle. Returns file metadata including a public CDN URL (or null for private files).

Request

file

required

The file to upload. Max size depends on your plan (10MB-500MB).

string

Optional folder path to organize files. Example: images/avatars

boolean

default:"false"

Set to true to make the file private (requires secret key). Private files need signed URLs to access.

string

Auto-delete after this duration. Format: 1h, 7d, 30d. Omit for permanent storage.

Response

string

required

Unique file identifier. Example: f_abc123xyz

string

Public CDN URL. null for private files.

string

required

Original filename.

string

Folder path, or null if uploaded to root.

integer

required

File size in bytes.

string

MIME type. Example: image/jpeg

boolean

required

Whether the file is private.

string

ISO 8601 expiration timestamp, or null if permanent.

string

required

ISO 8601 creation timestamp.

Examples

Basic Upload

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@photo.jpg"

const form = new FormData();
form.append('file', file);

const response = await fetch('https://api.stashfyle.com/v1/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_xxx' },
  body: form
});

const data = await response.json();
console.log(data.url);

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://api.stashfyle.com/v1/upload',
        headers={'Authorization': 'Bearer sk_live_xxx'},
        files={'file': f}
    )

print(response.json()['url'])

file, _ := os.Open("photo.jpg")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "photo.jpg")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.stashfyle.com/v1/upload", body)
req.Header.Set("Authorization", "Bearer sk_live_xxx")
req.Header.Set("Content-Type", writer.FormDataContentType())

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

Response

{
  "id": "f_abc123xyz",
  "url": "https://cdn.stashfyle.com/live/user_123/f_abc123xyz/photo.jpg",
  "name": "photo.jpg",
  "folder": null,
  "size": 248000,
  "type": "image/jpeg",
  "private": false,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Upload to Folder

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@avatar.png" \
  -F "folder=users/avatars"

Private File

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@document.pdf" \
  -F "private=true"

Response

{
  "id": "f_xyz789abc",
  "url": null,
  "name": "document.pdf",
  "private": true,
  ...
}

Auto-Expiring File

curl -X POST https://api.stashfyle.com/v1/upload \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "file=@temp-report.pdf" \
  -F "expires=7d"

Response

{
  "id": "f_temp123",
  "expires_at": "2024-01-22T10:30:00Z",
  ...
}

Errors

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Public key with invalid origin
`bad_request`	400	Missing file or invalid parameters
`file_too_large`	413	File exceeds plan limit
`storage_limit_exceeded`	413	Storage quota exceeded
`grace_period`	403	Account in grace period
`rate_limit_exceeded`	429	Too many requests

Overview

Uploads

Files

Signed URLs

Account

Upload File

Request

Response

Examples

Basic Upload

Upload to Folder

Private File

Auto-Expiring File

Errors

​Request

​Response

​Examples

​Basic Upload

​Upload to Folder

​Private File

​Auto-Expiring File

​Errors

Request

Response

Examples

Basic Upload

Upload to Folder

Private File

Auto-Expiring File

Errors