Revelator Logo API
v1

Files

The Files API provides a multipart upload workflow for securely uploading binary files, such as audio recordings and cover artwork. Once assembled, the API returns a permanent fileUrl that you can reference in other catalog endpoint payloads.

Files uploaded through these endpoints can only be used with the V2.0 API endpoints. They are not compatible with V1.0 API endpoints. Likewise, files uploaded via V1.0 endpoints (e.g., POST /media/image/upload) cannot be referenced in V2.0 API payloads.

Upload Workflow

Uploading a file is a three-step process:

  1. Create - Call POST /files/v1/uploads/create to initialize the upload. The response provides an uploadId, the suggested total number of parts, and the default chunkSizeBytes (10,000,000 bytes / 10MB)

  2. Sign & upload each part - For every part number from 1 to parts, call POST /files/v1/uploads/sign-part to receive a pre-signed url, the required HTTP method (typically PUT), necessary headers, and an expiry timestamp.

  • Optional Splitting (Recommended for Speed): Splitting your file into the suggested number of chunks allows you to sign and upload multiple parts in parallel, which significantly reduces total upload time.
  • Single Upload (Alternative): Chunking is optional. If the API suggests 2 parts, you can simply sign part 1, upload the entire file to that single signed URL, and ignore part 2.
  • Time Limit: Pre-signed URLs are valid for exactly 20 minutes. If you attempt to upload to the URL after it expires, it will return a 403 Forbidden error.
  1. Complete - Once your parts (or single full file) have been uploaded successfully, call POST /files/v1/uploads/complete with the uploadId and an array of the uploaded part numbers.
  • Note: The parts array only needs to contain the parts you actually uploaded (e.g., just [1] if you uploaded the whole file at once).
  • On success, the API returns the final assembled fileUrl.

Supported File Types

The purpose field determines which content types are accepted for a given upload.

PurposeAccepted content types
Image, CoverImageimage/jpeg image/jpg image/png image/gif image/webp image/bmp
File, GenericFileimage/jpeg image/jpg image/png image/gif image/webp image/bmp audio/wav application/pdf application/msword application/vnd.openxmlformats-officedocument.wordprocessingml.document
Videovideo/mp4 video/mpeg video/quicktime video/webm video/x-msvideo
Audioaudio/wav audio/mpeg audio/mp3 audio/ogg audio/webm audio/aac

Create Upload

POST /files/v1/uploads/create

Initializes a new upload session. Returns the upload ID, the suggested chunk size, and the suggested number of parts.

Request Body *

object
fileName string
Original file name including extension.
Examples: cover.jpg, recording.wav
contentType string
MIME type of the file. Must be a content type accepted by the chosen 'purpose'. See the Supported File Types table above.
Examples: image/jpeg, image/png, audio/wav, audio/mpeg, video/mp4, application/pdf
size integer
Total size of the file in bytes.
purpose string
Intended use of the file. Determines which content types are accepted and how the file is stored and processed after upload. See the Supported File Types table above.
Examples: Image, CoverImage, File, GenericFile, Video, Audio

Responses

object
uploadId string
Unique upload session ID to pass to subsequent sign-part and complete calls.
chunkSizeBytes integer
Suggested size in bytes of each chunk (default is 10,000,000 bytes). Splitting the file is optional but recommended for faster parallel uploads.
parts integer
Suggested total number of parts based on file size. You can split the file to upload in parallel, or simply upload the entire file as part 1.
POST /files/v1/uploads/create 
curl -X POST "https://platform.revelator.com/files/v1/uploads/create" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "fileName": "midnight-tides-cover",
  "contentType": "image/jpeg",
  "size": 10485760,
  "purpose": "CoverImage"
}'
Example response 200 
{
  "uploadId": "d9fad28c-c3d5-459b-9aa4-2e64ab679924",
  "chunkSizeBytes": 10000000,
  "parts": 2
}

Sign Part

POST /files/v1/uploads/sign-part

Returns a pre-signed URL for uploading a file part. PUT the binary chunk directly to the returned URL using the provided headers.

Request Body *

object
uploadId string
The upload session ID returned by the Create Upload endpoint.
partNumber integer
Part number to sign, starting at `1`. If you are not splitting the file, just sign part `1`.

Responses

object
method string
HTTP method to use when uploading the chunk to the signed URL (typically `PUT`).
url string
Pre-signed URL to which the binary payload should be uploaded.
headers object
Key-value map of HTTP headers that must be included in the upload request to the signed URL.
expiresAtUtc string (date-time)
UTC timestamp after which the signed URL is no longer valid (20 minutes from creation). Uploads attempted after this time will return a 403 Forbidden.
POST /files/v1/uploads/sign-part 
curl -X POST "https://platform.revelator.com/files/v1/uploads/sign-part" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "uploadId": "d9fad28c-c3d5-459b-9aa4-2e64ab679924",
  "partNumber": 1
}'
Example response 200 
{
  "method": "PUT",
  "url": "https://revelatorstage.blob.core.windows.net/temp-uploads/...",
  "headers": {
      "Content-Type": "application/octet-stream",
      "x-ms-blob-type": "BlockBlob"
  },
  "expiresAtUtc": "2026-03-17T10:18:53.7017793Z"
}

Complete Upload

POST /files/v1/uploads/complete

Finalizes the upload workflow after your parts (or single file) have been uploaded to their signed URLs. Returns the permanent file URL.

Request Body *

object
uploadId string
The upload session ID returned by the Create Upload endpoint.
parts integer[]
Array of part numbers that you actually uploaded (e.g., `[1]` if you uploaded the entire file at once, or `[1, 2]` if you split it).

Responses

object
fileUrl string
Permanent URL of the assembled file. Use this value in V2.0 API payloads that accept file references.
POST /files/v1/uploads/complete 
curl -X POST "https://platform.revelator.com/files/v1/uploads/complete" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"uploadId": "dad5931c-c728-4dfb-bda5-bd67a1905303",
"parts": [
  2,
  1
]
}'
Example response 200 
{
  "fileUrl": "https://revelatorstage.blob.core.windows.net/images/00000000-0000-0000-0000-000000000000/file.jpg"
}