File Uploads

This page describes the REST API for uploading files. For details on authentication, refer to the Authentication page, and for general guidelines, see API Guidelines.

Overview

The file upload endpoint allows you to initiate an upload by providing the file’s name and size. You will receive an upload ID along with a presigned URL to which you can upload your file.

File uploads are publicly accessible

Once uploaded, files are publicly accessible by anyone via a URL derived from the content hash. Do not upload files you don’t want to be publicly accessible.

Prerequisites

To use the file uploads API:

• Authenticate your requests.
• Follow the API Guidelines for all REST API requests.

Quick Start

Initiate a file upload:

curl -X POST https://api.royal.io/v0/files/upload \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "epic-meme.jpg",
    "size": 13716
  }'

The response includes an upload ID and a URL for uploading the file:

{
  "id": "01949a3a-c589-7fab-be22-10ae1de60b0d",
  "url": "https://royal-prod-uploads-inbox.s3-accelerate.amazonaws.com/app/[...truncated...]"
}

To upload the file, send a PUT request with the file’s contents:

curl -X PUT https://royal-prod-uploads-inbox.s3-accelerate.amazonaws.com/app/[...truncated...] \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 13716" \
  -d @epic-meme.jpg

Check the upload status:

curl https://api.royal.io/v0/files/<upload_id>

A successful upload returns HTTP 200 with a content hash:

{
  "id": "01949a3a-c589-7fab-be22-10ae1de60b0d",
  "content_hash": "0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b"
}

If the file has not been processed, a 404 error is returned.

Accessing uploaded files

Uploaded files are publicly accessible by anyone via a URL derived from the content hash and under the domain useruploads.com, i.e. https://useruploads.com/app/<content_hash>. For example:

https://useruploads.com/app/0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b

API Endpoints

Create File Upload

POST /v0/files/upload

Request Format

Headers

Header	Value
Authorization	Bearer ryl_sk_YOUR_SECRET_KEY
Content-Type	application/json

Body Fields

Field	Type	Required	Description
filename	string	Yes	The name of the file to upload.
size	number	Yes	The size of the file in bytes.

Example Request:

curl -X POST https://api.royal.io/v0/files/upload \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "epic-meme.jpg",
    "size": 13716
  }'

Example Response:

{
  "id": "01949a3a-c589-7fab-be22-10ae1de60b0d",
  "url": "https://royal-prod-uploads-inbox.s3-accelerate.amazonaws.com/app/[...truncated...]"
}

Get File

GET /v0/files/:upload_id

Response Format

Success (200 OK):

{
  "id": "01949a3a-c589-7fab-be22-10ae1de60b0d",
  "content_hash": "0f72c9b3a4141c769bf6dc69962f221c2cb5bf860487f3257c97781fa4cf323b"
}

Error (404):

Indicates the file has not been processed.