@spec avatar(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1FilesFileAvatar.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

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.

Raw image bytes of the agent avatar, served with the file's original content type.

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Files.Input.t()
) ::
  {:ok, ArchAstro.Types.StorageFile.t()} | {:error, ArchAstro.Error.reason()}

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.

Pass share: true to additionally mint a stable public URL for the file (returned as share_url), fetchable by anyone without authentication — for example to embed an uploaded image in a GitHub PR body or other external markdown. The URL does not expire. Sharing is revoked by setting share: false on PATCH /api/v1/files/:file with the same credential (or archastro update file <id> --unshare); re-enabling sharing reactivates previously issued URLs. Only image content types can be shared.

Returns 422 when the data field is not valid base64, the changeset is invalid, or share is requested for a non-image content type. Returns 403 when the request lacks the required app scope.

The newly created file, including a signed download URL.

@spec org_logo(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1FilesFileOrgLogo.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

Fetch an org logo image

Returns the raw image bytes for an organization's logo identified by file. This endpoint backs the org_logo.url field of catalog payloads (such as GET /api/v1/solutions), which anonymous consumers — the public marketplace's page cache, OpenGraph scrapers — may hold far longer than a signed storage URL lives. Authorization is performed via a short, stable capability token rather than an HTTP header, so the URL never expires.

The token is an HMAC-based capability tied to the file ID. It does not expire, but it is invalidated when the org's logo is replaced or removed — 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 org logo — return a uniform 404 to avoid acting as an existence oracle.

Raw image bytes of the org logo, served with the file's original content type.

@spec share(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1FilesFileShare.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

Fetch a publicly shared file

Returns the raw image bytes for a file that was explicitly shared for public access, identified by file. This endpoint is designed for consumers that hold a URL far longer than a signed storage URL lives — GitHub PR bodies (whose camo image proxy re-fetches from the origin URL), wikis, and issue trackers — and fetch it 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 sharing is turned off for the file (share: false on the file update endpoint) or the file is deleted — shared caches may continue serving the bytes 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. Only image content types are served.

All failure modes — invalid file ID, invalid token, file not currently shared — return a uniform 404 to avoid acting as an existence oracle.

Raw image bytes of the shared file, served with the file's original content type.

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1FilesFile.Input.t()
) :: {:ok, ArchAstro.Types.StorageFile.t()} | {:error, ArchAstro.Error.reason()}

Update a file

Updates mutable fields of an existing file. Only the fields you supply are changed; omitted fields retain their current values. The file's stored content and content_type cannot be changed after creation.

This endpoint is the companion to share: true on file upload: the same credential that granted public sharing can revoke it here with share: false (or grant it later with share: true; only image content types can be shared, and re-enabling sharing reactivates any previously issued share URLs). App scope is derived from the authenticated viewer, matching upload.

A file that exists but is not visible to the current viewer returns 404 rather than 403 to avoid revealing the file's existence.

The updated file, including a signed download URL.