Files

Upload an authenticated workspace file

Uploads the multipart file and returns its final public URL/key. Active HTML, JavaScript, XML and SVG content/extensions are rejected. HEIC/HEIF images are converted to JPEG, so use the returned key and filename. Storage or receipt failures return500; invalid files, MIME/key mismatches or conversion failures return422. Accepts approved generated basename keys and shared trip/sticker namespaces, current-workspace newsletter keys, validated account-logo/program-placeholder/email-template image keys, and current-workspace donation attachment keys. Donation attachments permit PDF, office documents, text/CSV and common images up to10MiB. This endpoint stores bytes; callers attach the returned key through the owning feature API. Requires permission: one of admins, manage_programs, donors_manage, manage_settings, access_account_settings, access_payment_gateways, imports_manage.

POST

storage

uploads

curl --request POST \
  --url https://api.gratona.com/v1/storage/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form key=550e8400-e29b-41d4-a716-446655440000.jpg \
  --form content_type=image/jpeg

import requests

url = "https://api.gratona.com/v1/storage/uploads"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "key": "550e8400-e29b-41d4-a716-446655440000.jpg",
    "content_type": "image/jpeg"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('key', '550e8400-e29b-41d4-a716-446655440000.jpg');
form.append('content_type', 'image/jpeg');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.gratona.com/v1/storage/uploads', 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.gratona.com/v1/storage/uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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.gratona.com/v1/storage/uploads"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.gratona.com/v1/storage/uploads")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/storage/uploads")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--"

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

{
  "status": "success",
  "key": "550e8400-e29b-41d4-a716-446655440000.jpeg",
  "content_type": "image/jpeg",
  "filename": "photo.jpeg",
  "converted": false,
  "url": "https://cdn.example.org/photo.jpeg",
  "upload_receipt": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

Authorizations

Authorization

string

header

required

Passport bearer token authentication for legacy admin sessions.

Body

multipart/form-data

Validated request fields for this operation.

file

required

Multipart file. Deployed PHP upload/post limits apply; direct images are additionally limited to50MiB and donation attachments to10MiB.

key

string

required

Permitted storage object key. URL-decoded and trimmed; empty, control characters, backslashes and dot/path-traversal segments are rejected.

Maximum string length: 1024

Example:

"550e8400-e29b-41d4-a716-446655440000.jpg"

content_type

string | null

Optional declared MIME type; must match detected content except validated CSV/plain-text and HEIC compatibility cases.

Maximum string length: 191

Example:

"image/jpeg"

Response

Operation result.

status

string

HTTP contracts traced from the deployed controller and delegated validation/serialization.

Example:

"success"

key

string

Final stored key; HEIC conversion can change the extension.

Example:

"550e8400-e29b-41d4-a716-446655440000.jpeg"

content_type

string

Stored MIME type.

Example:

"image/jpeg"

filename

string

Original filename, adjusted when converted.

Example:

"photo.jpeg"

converted

boolean

Whether the original HEIC/HEIF was converted to JPEG.

Example:

false

url

string<uri>

Public file URL.

Example:

"https://cdn.example.org/photo.jpeg"

upload_receipt

string<uuid>

Recipient-session attachment receipt UUID when eligible. Expires after60minutes and is bound to that session, record and key.

Upload an authenticated workspace file

curl --request POST \
  --url https://api.gratona.com/v1/storage/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form key=550e8400-e29b-41d4-a716-446655440000.jpg \
  --form content_type=image/jpeg

import requests

url = "https://api.gratona.com/v1/storage/uploads"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "key": "550e8400-e29b-41d4-a716-446655440000.jpg",
    "content_type": "image/jpeg"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('key', '550e8400-e29b-41d4-a716-446655440000.jpg');
form.append('content_type', 'image/jpeg');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.gratona.com/v1/storage/uploads', 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.gratona.com/v1/storage/uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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.gratona.com/v1/storage/uploads"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.gratona.com/v1/storage/uploads")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/storage/uploads")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"key\"\r\n\r\n550e8400-e29b-41d4-a716-446655440000.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"content_type\"\r\n\r\nimage/jpeg\r\n-----011000010111000001101001--"

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

{
  "status": "success",
  "key": "550e8400-e29b-41d4-a716-446655440000.jpeg",
  "content_type": "image/jpeg",
  "filename": "photo.jpeg",
  "converted": false,
  "url": "https://cdn.example.org/photo.jpeg",
  "upload_receipt": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}