Skip to main content
POST
Pre-upload a file

Authorizations

Authorization
string
header
required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Body

application/json
filename
string
required

Name of the file to upload

Required string length: 1 - 255
content_type
enum<string>
required

Supported declared MIME types for uploaded Attachments and media URLs. Relay stores and returns the original bytes unchanged. Relay accepts WebP and rejects SVG as an explicit content-safety decision.

Available options:
image/jpeg,
image/png,
image/gif,
image/heic,
image/heif,
image/tiff,
image/bmp,
image/webp,
image/x-icon,
video/mp4,
video/quicktime,
video/mpeg,
video/mpeg2,
video/x-m4v,
video/x-msvideo,
video/3gpp,
audio/mpeg,
audio/mp3,
audio/x-m4a,
audio/mp4,
audio/x-caf,
audio/x-wav,
audio/x-aiff,
audio/aiff,
audio/aac,
audio/midi,
audio/amr,
application/pdf,
application/vnd.apple.pkpass,
text/plain,
text/markdown,
text/vcard,
text/rtf,
text/csv,
text/html,
text/calendar,
application/msword,
application/vnd.openxmlformats-officedocument.wordprocessingml.document,
application/vnd.ms-excel,
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.ms-powerpoint,
application/vnd.openxmlformats-officedocument.presentationml.presentation,
application/x-iwork-pages-sffpages,
application/x-iwork-numbers-sffnumbers,
application/x-iwork-keynote-sffkey,
application/epub+zip,
text/xml,
application/json,
application/zip,
application/x-gzip
size_bytes
integer<int64>
required

Size of the file in bytes (max 100MB)

Required range: 1 <= x <= 104857600
duration_ms
integer | null

Audio or video duration in milliseconds when known.

Required range: x >= 0
width
integer | null

Pixel width when known. Width and height are supplied together.

Required range: x >= 1
height
integer | null

Pixel height when known. Width and height are supplied together.

Required range: x >= 1

Response

Upload URL generated successfully

attachment_id
string<uuid>
required

Unique identifier for the attachment

upload_url
string<uri>
required

Opaque Relay upload URL. PUT the raw bytes with the exact required_headers before expires_at.

download_url
string<uri>
required

Opaque Relay download URL for the Attachment.

http_method
enum<string>
required

HTTP method to use for upload (always PUT)

Available options:
PUT
expires_at
string<date-time>
required

When the upload URL expires (15 minutes from now)

required_headers
object
required

Exact HTTP headers required by the upload URL.