class

Anthropic::BetaFiles

Files API for uploading and managing files (Beta)

All methods require the beta header files-api-2025-04-14. Access via client.beta.files.

# Upload a file
file = client.beta.files.upload(File.open("document.pdf"))

# Use in a message
message = client.beta.messages.create(
  betas: [Anthropic::FILES_API_BETA],
  model: Anthropic::Model::CLAUDE_SONNET_4_6,
  max_tokens: 1024,
  messages: [{
    role:    "user",
    content: [
      {type: "text", text: "Summarize this document"},
      {type: "document", source: {type: "file", file_id: file.id}},
    ],
  }]
)

# Clean up
client.beta.files.delete(file.id)

Constants

BETA_HEADER = "files-api-2025-04-14"

Constructors

new(client : Client)

Source

Instance methods

delete(file_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : DeletedFile

Delete a file

result = client.beta.files.delete("file_abc123")
puts result.id # => "file_abc123"

Source

download(file_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : IO::Memory

Download file content

Only files created by Claude (via code execution tool) can be downloaded. Uploaded files cannot be downloaded - use the original file instead.

if file.downloadable
  content = client.beta.files.download(file.id)
  File.write("output.txt", content.to_s)
end

Source

list(ids : Array(String) | Nil = nil, limit : Int32 = 20, page : String | Nil = nil, scope_id : String | Nil = nil, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : FileListResponse

List uploaded files

files = client.beta.files.list(limit: 10)
files.data.each { |f| puts f.filename }

# Pagination
if page = files.next_page
  more = client.beta.files.list(page: page)
end

# Get all files
all_files = files.auto_paging_all(client)

Source

retrieve(file_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : FileMetadata

Alias for retrieve_metadata.

Source

retrieve_metadata(file_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : FileMetadata

Get metadata for a specific file

file = client.beta.files.retrieve_metadata("file_abc123")
puts file.filename
puts file.size_bytes

Source

upload(file : Path, content_type : String | Nil = nil, expires_in_seconds : Int32 | Nil = nil, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : FileMetadata

Upload a file

Supported file types:

PDFs: application/pdf
Plain text: text/plain
Images: image/jpeg, image/png, image/gif, image/webp

Files can be up to 500 MB in size.

# Upload from file path
file = client.beta.files.upload(Path["document.pdf"])

# Upload from IO
file = client.beta.files.upload(
  File.open("image.png"),
  filename: "my_image.png",
  content_type: "image/png"
)

Source

upload(file : IO, filename : String = "file", content_type : String = "application/octet-stream", expires_in_seconds : Int32 | Nil = nil, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : FileMetadata

Upload a file

Supported file types:

PDFs: application/pdf
Plain text: text/plain
Images: image/jpeg, image/png, image/gif, image/webp

Files can be up to 500 MB in size.

# Upload from file path
file = client.beta.files.upload(Path["document.pdf"])

# Upload from IO
file = client.beta.files.upload(
  File.open("image.png"),
  filename: "my_image.png",
  content_type: "image/png"
)

Source