Files API (Beta) - Ruby SDK Reference

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Ruby SDK reference for the Anthropic Files API beta, covering file upload, listing, downloading, metadata retrieval, and deletion operations for developers integrating file handling into their Claude AI applications.

Insight

The Files API provides five main operations accessible via the beta.files namespace. Upload (beta.files.upload) accepts a file parameter and optional beta headers, returning a FileMetadata object with id, created_at, filename, mime_type, size_bytes, type (:file), downloadable boolean, and scope information. List (beta.files.list) supports pagination with after_id/before_id cursors, limit (1-1000, default 20), and scope_id filtering, returning a Page<FileMetadata>. Download (beta.files.download) takes a file_id and returns StringIO containing the file content via GET /v1/files/{file_id}/content. Retrieve Metadata (beta.files.retrieve_metadata) returns FileMetadata for a specific file via GET /v1/files/{file_id}. Delete (beta.files.delete) removes a file and returns a DeletedFile object with id and type (:file_deleted). The BetaFileScope class indicates the context where files were created (e.g., session), containing id and type (:session). All operations support an optional betas parameter accepting beta version strings such as :files-api-2025-04-14, :pdfs-2024-09-25, :prompt-caching-2024-07-31, :computer-use-2024-10-22, and many others including future-dated beta identifiers.

Hành động

Initialize the Anthropic client with your API key, then call methods on the beta.files namespace. To upload: pass a file (e.g., StringIO or File object) to upload(file: ...). To list: call list with optional pagination cursors (after_id, before_id), limit (1-1000), or scope_id. To download: pass a file_id to download(file_id). To get metadata: pass a file_id to retrieve_metadata(file_id). To delete: pass a file_id to delete(file_id). All methods accept optional betas: parameter with an array of beta version symbols (e.g., betas: [:“files-api-2025-04-14”]). The API follows REST conventions: POST for upload, GET for list/content/metadata, DELETE for removal.

Kết quả

Upload returns FileMetadata with id, created_at, filename, mime_type, size_bytes, type (:file), downloadable bool, and scope. List returns Page with pagination support. Download returns StringIO with file content. Retrieve metadata returns FileMetadata. Delete returns DeletedFile with id and type (:file_deleted).

Điều kiện áp dụng

Beta API - requires optional betas parameter with a valid beta version string such as :“files-api-2025-04-14” or other beta identifier listed in the documentation.

Nội dung gốc (Original)

Files

Upload

beta.files.upload(**kwargs) -> FileMetadata

post /v1/files

Upload File

Parameters

file: String

The file to upload
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.
- String
- :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 21 more
  - :"message-batches-2024-09-24"
  - :"prompt-caching-2024-07-31"
  - :"computer-use-2024-10-22"
  - :"computer-use-2025-01-24"
  - :"pdfs-2024-09-25"
  - :"token-counting-2024-11-01"
  - :"token-efficient-tools-2025-02-19"
  - :"output-128k-2025-02-19"
  - :"files-api-2025-04-14"
  - :"mcp-client-2025-04-04"
  - :"mcp-client-2025-11-20"
  - :"dev-full-thinking-2025-05-14"
  - :"interleaved-thinking-2025-05-14"
  - :"code-execution-2025-05-22"
  - :"extended-cache-ttl-2025-04-11"
  - :"context-1m-2025-08-07"
  - :"context-management-2025-06-27"
  - :"model-context-window-exceeded-2025-08-26"
  - :"skills-2025-10-02"
  - :"fast-mode-2026-02-01"
  - :"output-300k-2026-03-24"
  - :"user-profiles-2026-03-24"
  - :"advisor-tool-2026-03-01"
  - :"managed-agents-2026-04-01"

Returns

class FileMetadata
- id: String
  
  Unique object identifier.
  
  The format and length of IDs may change over time.
- created_at: Time
  
  RFC 3339 datetime string representing when the file was created.
- filename: String
  
  Original filename of the uploaded file.
- mime_type: String
  
  MIME type of the file.
- size_bytes: Integer
  
  Size of the file in bytes.
- type: :file
  
  Object type.
  
  For files, this is always "file".
  - :file
- downloadable: bool
  
  Whether the file can be downloaded.
- scope: BetaFileScope
  
  The scope of this file, indicating the context in which it was created (e.g., a session).
  - id: String
    
    The ID of the scoping resource (e.g., the session ID).
  - type: :session
    
    The type of scope (e.g., "session").
    - :session

Example

require "anthropic"
 
anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")
 
file_metadata = anthropic.beta.files.upload(file: StringIO.new("Example data"))
 
puts(file_metadata)

List

beta.files.list(**kwargs) -> Page<FileMetadata>

get /v1/files

List Files

Parameters

after_id: String

ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: String

ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
limit: Integer

Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.
scope_id: String

Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.
- String
- :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 21 more
  - :"message-batches-2024-09-24"
  - :"prompt-caching-2024-07-31"
  - :"computer-use-2024-10-22"
  - :"computer-use-2025-01-24"
  - :"pdfs-2024-09-25"
  - :"token-counting-2024-11-01"
  - :"token-efficient-tools-2025-02-19"
  - :"output-128k-2025-02-19"
  - :"files-api-2025-04-14"
  - :"mcp-client-2025-04-04"
  - :"mcp-client-2025-11-20"
  - :"dev-full-thinking-2025-05-14"
  - :"interleaved-thinking-2025-05-14"
  - :"code-execution-2025-05-22"
  - :"extended-cache-ttl-2025-04-11"
  - :"context-1m-2025-08-07"
  - :"context-management-2025-06-27"
  - :"model-context-window-exceeded-2025-08-26"
  - :"skills-2025-10-02"
  - :"fast-mode-2026-02-01"
  - :"output-300k-2026-03-24"
  - :"user-profiles-2026-03-24"
  - :"advisor-tool-2026-03-01"
  - :"managed-agents-2026-04-01"

Returns

class FileMetadata
- id: String
  
  Unique object identifier.
  
  The format and length of IDs may change over time.
- created_at: Time
  
  RFC 3339 datetime string representing when the file was created.
- filename: String
  
  Original filename of the uploaded file.
- mime_type: String
  
  MIME type of the file.
- size_bytes: Integer
  
  Size of the file in bytes.
- type: :file
  
  Object type.
  
  For files, this is always "file".
  - :file
- downloadable: bool
  
  Whether the file can be downloaded.
- scope: BetaFileScope
  
  The scope of this file, indicating the context in which it was created (e.g., a session).
  - id: String
    
    The ID of the scoping resource (e.g., the session ID).
  - type: :session
    
    The type of scope (e.g., "session").
    - :session

Example

require "anthropic"
 
anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")
 
page = anthropic.beta.files.list
 
puts(page)

Download

beta.files.download(file_id, **kwargs) -> StringIO

get /v1/files/{file_id}/content

Download File

Parameters

file_id: String

ID of the File.
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.
- String
- :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 21 more
  - :"message-batches-2024-09-24"
  - :"prompt-caching-2024-07-31"
  - :"computer-use-2024-10-22"
  - :"computer-use-2025-01-24"
  - :"pdfs-2024-09-25"
  - :"token-counting-2024-11-01"
  - :"token-efficient-tools-2025-02-19"
  - :"output-128k-2025-02-19"
  - :"files-api-2025-04-14"
  - :"mcp-client-2025-04-04"
  - :"mcp-client-2025-11-20"
  - :"dev-full-thinking-2025-05-14"
  - :"interleaved-thinking-2025-05-14"
  - :"code-execution-2025-05-22"
  - :"extended-cache-ttl-2025-04-11"
  - :"context-1m-2025-08-07"
  - :"context-management-2025-06-27"
  - :"model-context-window-exceeded-2025-08-26"
  - :"skills-2025-10-02"
  - :"fast-mode-2026-02-01"
  - :"output-300k-2026-03-24"
  - :"user-profiles-2026-03-24"
  - :"advisor-tool-2026-03-01"
  - :"managed-agents-2026-04-01"

Returns

StringIO

Example

require "anthropic"
 
anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")
 
response = anthropic.beta.files.download("file_id")
 
puts(response)

Retrieve Metadata

beta.files.retrieve_metadata(file_id, **kwargs) -> FileMetadata

get /v1/files/{file_id}

Get File Metadata

Parameters

file_id: String

ID of the File.
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.
- String
- :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 21 more
  - :"message-batches-2024-09-24"
  - :"prompt-caching-2024-07-31"
  - :"computer-use-2024-10-22"
  - :"computer-use-2025-01-24"
  - :"pdfs-2024-09-25"
  - :"token-counting-2024-11-01"
  - :"token-efficient-tools-2025-02-19"
  - :"output-128k-2025-02-19"
  - :"files-api-2025-04-14"
  - :"mcp-client-2025-04-04"
  - :"mcp-client-2025-11-20"
  - :"dev-full-thinking-2025-05-14"
  - :"interleaved-thinking-2025-05-14"
  - :"code-execution-2025-05-22"
  - :"extended-cache-ttl-2025-04-11"
  - :"context-1m-2025-08-07"
  - :"context-management-2025-06-27"
  - :"model-context-window-exceeded-2025-08-26"
  - :"skills-2025-10-02"
  - :"fast-mode-2026-02-01"
  - :"output-300k-2026-03-24"
  - :"user-profiles-2026-03-24"
  - :"advisor-tool-2026-03-01"
  - :"managed-agents-2026-04-01"

Returns

class FileMetadata
- id: String
  
  Unique object identifier.
  
  The format and length of IDs may change over time.
- created_at: Time
  
  RFC 3339 datetime string representing when the file was created.
- filename: String
  
  Original filename of the uploaded file.
- mime_type: String
  
  MIME type of the file.
- size_bytes: Integer
  
  Size of the file in bytes.
- type: :file
  
  Object type.
  
  For files, this is always "file".
  - :file
- downloadable: bool
  
  Whether the file can be downloaded.
- scope: BetaFileScope
  
  The scope of this file, indicating the context in which it was created (e.g., a session).
  - id: String
    
    The ID of the scoping resource (e.g., the session ID).
  - type: :session
    
    The type of scope (e.g., "session").
    - :session

Example

require "anthropic"
 
anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")
 
file_metadata = anthropic.beta.files.retrieve_metadata("file_id")
 
puts(file_metadata)

Delete

beta.files.delete(file_id, **kwargs) -> DeletedFile

delete /v1/files/{file_id}

Delete File

Parameters

file_id: String

ID of the File.
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.
- String
- :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 21 more
  - :"message-batches-2024-09-24"
  - :"prompt-caching-2024-07-31"
  - :"computer-use-2024-10-22"
  - :"computer-use-2025-01-24"
  - :"pdfs-2024-09-25"
  - :"token-counting-2024-11-01"
  - :"token-efficient-tools-2025-02-19"
  - :"output-128k-2025-02-19"
  - :"files-api-2025-04-14"
  - :"mcp-client-2025-04-04"
  - :"mcp-client-2025-11-20"
  - :"dev-full-thinking-2025-05-14"
  - :"interleaved-thinking-2025-05-14"
  - :"code-execution-2025-05-22"
  - :"extended-cache-ttl-2025-04-11"
  - :"context-1m-2025-08-07"
  - :"context-management-2025-06-27"
  - :"model-context-window-exceeded-2025-08-26"
  - :"skills-2025-10-02"
  - :"fast-mode-2026-02-01"
  - :"output-300k-2026-03-24"
  - :"user-profiles-2026-03-24"
  - :"advisor-tool-2026-03-01"
  - :"managed-agents-2026-04-01"

Returns

class DeletedFile
- id: String
  
  ID of the deleted file.
- type: :file_deleted
  
  Deleted object type.
  
  For file deletion, this is always "file_deleted".
  - :file_deleted

Example

require "anthropic"
 
anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")
 
deleted_file = anthropic.beta.files.delete("file_id")
 
puts(deleted_file)

Domain Types

Beta File Scope

class BetaFileScope
- id: String
  
  The ID of the scoping resource (e.g., the session ID).
- type: :session
  
  The type of scope (e.g., "session").
  - :session

Deleted File

class DeletedFile
- id: String
  
  ID of the deleted file.
- type: :file_deleted
  
  Deleted object type.
  
  For file deletion, this is always "file_deleted".
  - :file_deleted

File Metadata

class FileMetadata
- id: String
  
  Unique object identifier.
  
  The format and length of IDs may change over time.
- created_at: Time
  
  RFC 3339 datetime string representing when the file was created.
- filename: String
  
  Original filename of the uploaded file.
- mime_type: String
  
  MIME type of the file.
- size_bytes: Integer
  
  Size of the file in bytes.
- type: :file
  
  Object type.
  
  For files, this is always "file".
  - :file
- downloadable: bool
  
  Whether the file can be downloaded.
- scope: BetaFileScope
  
  The scope of this file, indicating the context in which it was created (e.g., a session).
  - id: String
    
    The ID of the scoping resource (e.g., the session ID).
  - type: :session
    
    The type of scope (e.g., "session").
    - :session

Liên kết

Nền tảng: Dev Framework · Anthropic
Nguồn: https://platform.claude.com/docs/en/api/ruby/beta/files.md

Xem thêm:

Archive Session Thread API
Create Message - Beta Messages API (Go)
Retrieve Model - Anthropic Models API Beta Reference
[[entries/models-retrieve-c-sdk|Models.Retrieve - C# SDK]]
Retrieve Model - Anthropic Models API

KakaFlow KB

Nội dung

Files API (Beta) - Ruby SDK Reference

Files API (Beta) - Ruby SDK Reference

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Files

Upload

Parameters

Returns

Example

List

Parameters

Returns

Example

Download

Parameters

Returns

Example

Retrieve Metadata

Parameters

Returns

Example

Delete

Parameters

Returns

Example

Domain Types

Beta File Scope

Deleted File

File Metadata

Liên kết

Sơ đồ

Mục lục

Liên kết ngược