Claudio.Files (Claudio v0.7.0)

Anthropic Files API client.

Upload files to Anthropic's storage so they can be referenced from message content blocks via the type: "document" / source: {type: "file", file_id} shape (see Claudio.Messages.Request.add_message_with_document/4).

GA — no beta header

The Files API is generally available; no anthropic-beta header is needed. Responses without the header use the GA shapes: list/2 returns %{"data" => [...], "next_page" => cursor | nil} and pages with :page (or fetches up to 100 known ids with :ids); before_id/after_id return 400.

Callers that still put files-api-2025-04-14 on their client keep the old beta shapes (has_more/first_id/last_id, :before_id/:after_id cursors, no expires_at) — Claudio passes whatever you choose through.

Example

{:ok, %{"id" => file_id}} =
  Claudio.Files.upload(client, bytes, content_type: "application/pdf",
    filename: "contract.pdf")

request =
  Claudio.Messages.Request.new("claude-opus-5-5")
  |> Claudio.Messages.Request.add_message_with_document(:user, "Summarise.", file_id)

Claudio.Messages.create(client, request)

# List, inspect, and clean up later:
{:ok, %{"data" => files}} = Claudio.Files.list(client, limit: 50)
{:ok, _meta} = Claudio.Files.get(client, file_id)
{:ok, bytes} = Claudio.Files.download(client, file_id)
{:ok, %{"type" => "file_deleted"}} = Claudio.Files.delete(client, file_id)

Summary

Functions

delete(client, file_id)

Deletes a file from the Anthropic Files API.

download(client, file_id)

Downloads the raw bytes of a file.

get(client, file_id)

Retrieves metadata for a single file.

list(client, opts \\ [])

Lists files uploaded to the Anthropic Files API.

upload(client, bytes, opts)

Upload bytes to the Anthropic Files API.

Functions

delete(client, file_id)

@spec delete(Req.Request.t(), String.t()) ::
  {:ok, map()} | {:error, Claudio.APIError.t() | term()}

Deletes a file from the Anthropic Files API.

Parameters

client — A Req.Request from Claudio.Client.new/2.
file_id — The file id to delete.

Returns

{:ok, %{"id" => _, "type" => "file_deleted"}} on success.
{:error, %Claudio.APIError{}} on a non-200 response.
{:error, term()} on a transport/Req error.

download(client, file_id)

@spec download(Req.Request.t(), String.t()) ::
  {:ok, binary()} | {:error, Claudio.APIError.t() | term()}

Downloads the raw bytes of a file.

Req auto-decodes JSON only when content-type: application/json; for any other content type (PDF, image, plain text, etc.), the response body is returned as a raw binary unchanged.

Parameters

client — A Req.Request from Claudio.Client.new/2.
file_id — The file id returned from upload/3.

Returns

{:ok, binary()} on success — the raw file contents.
{:error, %Claudio.APIError{}} on a non-200 response (error bodies are JSON).
{:error, term()} on a transport/Req error.

get(client, file_id)

@spec get(Req.Request.t(), String.t()) ::
  {:ok, map()} | {:error, Claudio.APIError.t() | term()}

Retrieves metadata for a single file.

Parameters

client — A Req.Request from Claudio.Client.new/2.
file_id — The file id returned from upload/3 (e.g. "file_abc123").

Returns

{:ok, %{"id" => _, "type" => "file", "filename" => _, "mime_type" => _, "size_bytes" => _, "created_at" => _, "downloadable" => _}} on success.
{:error, %Claudio.APIError{}} on a non-200 response.
{:error, term()} on a transport/Req error.

list(client, opts \\ [])

@spec list(
  Req.Request.t(),
  keyword()
) :: {:ok, map()} | {:error, Claudio.APIError.t() | term()}

Lists files uploaded to the Anthropic Files API.

Parameters

client — A Req.Request from Claudio.Client.new/2.
opts — Optional keyword list:
- :limit — Files per page (server default 20, max 1000).
- :page — Cursor from a previous response's "next_page".
- :ids — Up to 100 file ids, sent as repeated ids[]; returns a single page. Not combinable with :page/:limit (the API rejects it).
- :before_id / :after_id — Legacy cursors; only valid when the client sends the files-api-2025-04-14 beta header.

Returns

{:ok, %{"data" => [...], "next_page" => _}} (GA) or {:ok, %{"data" => [...], "first_id" => _, "last_id" => _, "has_more" => _}} (with the legacy beta header).
{:error, %Claudio.APIError{}} on a non-200 response.
{:error, term()} on a transport/Req error.

upload(client, bytes, opts)

@spec upload(Req.Request.t(), binary(), keyword()) ::
  {:ok, map()} | {:error, Claudio.APIError.t() | term()}

Upload bytes to the Anthropic Files API.

Parameters

client — A Req.Request from Claudio.Client.new/2.
bytes — The raw file contents as a binary.
opts — Keyword list. Required:
- :content_type — MIME type (e.g. "application/pdf").
- :filename — Filename string (used for the multipart filename part).

Optional:

  * `:expires_in_seconds` — Integer seconds from upload until the file expires
    (sent as a multipart form field). The API documents a range of 3600 (one hour)
    to 7776000 (ninety days) and rejects other values with a 400. Without it the
    file does not expire.

Returns

{:ok, %{"id" => "file_xxx", "type" => "file", "filename" => "...", "mime_type" => "...", "size_bytes" => N, "created_at" => "..."}} on success.
{:error, %Claudio.APIError{}} on a non-200 response.
{:error, term()} on a transport/Req error.