Claudio.Files (Claudio v0.5.0)

View Source

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).

Beta gating

The Files API is currently behind the files-api-2025-04-14 Anthropic beta flag. Pass it on the client built by Claudio.Client.new/2:

client = Claudio.Client.new(%{
  token: "sk-ant-...",
  beta: ["files-api-2025-04-14"]
})

Or set it globally via application config (applies to every Claudio call):

config :claudio, :claudio,
  default_beta_features: ["files-api-2025-04-14"]

Example

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

request =
  Claudio.Messages.Request.new("claude-sonnet-4-6")
  |> 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

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

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

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.

Beta gating

Requires the files-api-2025-04-14 Anthropic beta flag on the client (see moduledoc).

Parameters

  • client — A Req.Request from Claudio.Client.new/2.
  • opts — Optional keyword list:
    • :limit — Number of files to return (default server-side: 20).
    • :before_id — Cursor for the previous page (file id).
    • :after_id — Cursor for the next page (file id).

Returns

  • {:ok, %{"data" => [...], "first_id" => _, "last_id" => _, "has_more" => _}} on success.
  • {: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. Should have the files-api-2025-04-14 beta feature configured (see moduledoc).
  • bytes — The raw file contents as a binary.
  • opts — Required keyword list:
    • :content_type — MIME type (e.g. "application/pdf").
    • :filename — Filename string (used for the multipart filename part).

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.