Files

The gateway orchestrates signed URLs; file bytes are uploaded to or downloaded from object storage directly. Both routes require an OAuth bearer access token.

Method	Route	Purpose
POST	/api/v1/files/upload-urls	Generate an upload URL and object reference.
POST	/api/v1/files/read-urls	Generate a temporary read URL for an object path.

Upload pattern

1. Ask the gateway for an upload URL using the intended file metadata.
2. Upload bytes directly to the signed URL with the required method and headers.
3. Store or submit the returned object path—not the expiring signed URL—as the durable reference.

Signed URLs are short-lived capabilities. Do not log them or expose them to unrelated users.