Class FileResource

Fetch an agent avatar image Returns the raw image bytes for an agent's profile picture identified by file. This endpoint is designed for integration partners (such as Slack) that fetch avatar URLs via plain GET requests without bearer token support. Authorization is performed via a short, stable capability token rather than an HTTP header. The token is an HMAC-based capability tied to the file ID. It does not expire, but it is invalidated when the agent's profile picture is replaced or the agent is deleted — shared caches may continue serving the old image until the Cache-Control max-age of one hour elapses. The endpoint never redirects to a signed storage URL; bytes are served inline so behavior is consistent across storage backends. All failure modes — invalid file ID, invalid token, file not currently referenced as an agent avatar — return a uniform 404 to avoid acting as an existence oracle.

Upload a file Creates a new file from base64-encoded content and returns the resulting file object, including a signed download URL. Use this endpoint to store images, documents, or other binary assets that can then be referenced by agents, teams, or users. App scope is derived from the authenticated viewer's bearer token or publishable key. You may optionally associate the file with an organization, team, user, or agent by passing the corresponding ID. If no owner is specified and the viewer is a user, the file is automatically attributed to that user. Returns 422 when the data field is not valid base64 or the changeset is invalid. Returns 403 when the request lacks the required app scope.