Upload relay

The upload relay is where a client sends the bytes of a file. Each upload URL has a signed capability, and the relay stores the one object it authorises. Request attachment upload URLs and Create stream preview upload URL issue them. Attachment uploads states the flow the relay takes part in.

Base URL and authorisation

Paths here are relative to the relay base in the issued upload URL. That base is a deployment setting.

The capability is the complete authorisation. The relay reads no HTTP API Authorization header and has no request-count rate limit. The PUT has a deployment mode gate and returns 404 outside upload and relay mode.

Some upload URLs address object storage directly

An upload URL points directly to object storage when the caller’s IP address geolocates to a country the deployment lists in keep_direct_countries. Use the URL returned by the HTTP API. This page describes relay URLs only.

The complete URL is authenticated

The path key and the t capability are bound together by the signature. A client MUST use the URL exactly as issued and MUST NOT rebuild, decode, reorder, or re-encode it. The URL is a bearer capability.

Relay capability object

The t query parameter is an opaque bearer token. Keep it private and use it only with the issued URL. Upload URLs expire after 900 seconds by default. A missing, invalid or expired token returns 401.

Put relay object

PUT/v1/relay/{key}

Uploads the object or part authorised by the relay capability. Returns 200 with an empty body and an optional ETag header.

Path parameters

Field	Type	Description
key1	string	The object key of the issued URL

¹ Use the key exactly as it appears in the issued URL. Changing it returns 403

Query parameters

Field	Type	Description
t1	string	The opaque upload token
uploadId?2	string	The multipart upload identifier, present only when the capability has one
partNumber?3	integer	The multipart part number, present only when the capability has one

¹ A missing t returns 401

² Use the value from the issued URL. A missing or mismatched multipart upload identifier returns 403

³ An empty or unparsable value returns 400. A part number that does not match the issued URL returns 403

Request headers

Field	Type	Description
Content-Length?1	integer	The declared length of the request body
Content-Type?2	string	The media type to store, read only when the capability declares none

¹ A declared length above the authorised upload size or the endpoint body limit returns 413

² The media type authorised by the upload URL takes precedence

The relay ignores every other request header.

Request body

The body is arbitrary bytes.

When Content-Length is supplied, send exactly that many bytes. A longer body returns 413 and a shorter body returns 400. Without this header, a body above the authorised upload size or the endpoint body limit still returns 413. Interrupted uploads return 400, and insufficient relay capacity returns 503.

Response

The relay forwards no object storage response body and no arbitrary response headers.

Status	Body	Condition
200	empty	The object or part was stored
400	Bad Request	The partNumber value is unparsable or the client body ended early
401	Unauthorized	The capability is missing, malformed, incorrectly signed, or expired
403	Forbidden	The bucket, key, uploadId, or partNumber disagrees with the capability
404	Not Found	The endpoint does not serve the upload relay
4051	empty	The method is not PUT
413	Payload Too Large	The body exceeds the authorised upload size or the endpoint body limit
500	Internal Server Error	The relay could not store the upload locally
502	Bad Gateway	The object store refused the write or could not be written to
503	Service Unavailable	The relay has insufficient upload capacity

¹ It has no relay CORS headers and no cache policy

A message naming the key creates the attachment

A successful relay request stores the bytes and creates no attachment. Create message, Modify message, and Execute webhook are the requests that can name the key.

Complete attachment upload assembles a multipart upload once every part is stored, and a singlepart upload needs no completion step. A stream preview becomes readable as soon as the stored object is in place, and the Streams resource defines that flow.

Repeating an upload replaces the object or part, and the last successful write wins. A multipart part can be retried after a 502 or 503 while its URL remains valid.

Response headers

The 200, 400, 401, 403, 413, 500, 502, and 503 have the relay CORS headers. The 404 and the 405 have none of them.

Relay CORS means Access-Control-Allow-Origin: *, Access-Control-Allow-Headers: Content-Type, Content-Length, Authorization, X-FiveCord-Features, X-Client-Context, and Access-Control-Expose-Headers: ETag, X-FiveCord-Version.

Side effects

A successful request writes the object the capability selects to the uploads bucket. It creates no attachment record and no message.

Streaming limits

Setting	Default	Configurable range
Endpoint body limit	500 MiB	1 byte through 5 GiB
Object storage write deadline	900,000 ms	1,000 through 3,600,000 ms

The largest body the relay accepts is the smaller of the endpoint body limit and the authorised upload size.

When the request declares Content-Length, the relay extends the object storage write deadline by one second for every 16 KiB of declared length.