feat: add files api support

README.md

@@ -201,6 +201,150 @@ if (response.IsFailure)
 Console.WriteLine("Model Id: {0}", response.Value.Id);
 ```
 
+### Files API
+
+The `AnthropicApiClient` provides support for the Anthropic Files API, which allows you to upload and manage files for use with the Anthropic API.
+
+> [!NOTE]
+> The Files API is currently in beta. To use the Files API, you’ll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`
+
+#### Create a File
+
+You can create a file using the Files API in several ways:
+
+##### From a Byte Array
+
+```csharp
+var fileBytes = await File.ReadAllBytesAsync("path/to/file.txt");
+var request = new CreateFileRequest(fileBytes, "file.txt", "text/plain");
+var result = await client.CreateFileAsync(request);
+
+if (result.IsSuccess)
+{
+  var file = result.Value;
+  Console.WriteLine($"Created file: {file.Name} (ID: {file.Id})");
+}
+```
+
+##### From a Stream
+
+```csharp
+using var fileStream = File.OpenRead("path/to/file.txt");
+var request = new CreateFileRequest(fileStream, "file.txt", "text/plain");
+
+var result = await client.CreateFileAsync(request);
+
+if (result.IsSuccess)
+{
+    var file = result.Value;
+    Console.WriteLine($"Created file: {file.Name} (ID: {file.Id})");
+}
+```
+
+#### List Files
+
+You can list files in your account using pagination:
+
+##### Single Page
+
+```csharp
+var result = await client.ListFilesAsync();
+
+if (result.IsSuccess)
+{
+    var page = result.Value;
+    Console.WriteLine($"Found {page.Data.Count} files");
+
+    foreach (var file in page.Data)
+    {
+        Console.WriteLine($"- {file.Name} (ID: {file.Id}, Size: {file.Size} bytes)");
+    }
+
+    if (page.HasMore)
+    {
+        Console.WriteLine("More files available...");
+    }
+}
+```
+
+##### With Pagination Options
+
+```csharp
+var pagingRequest = new PagingRequest(afterId: "file_12345", limit: 10);
+var result = await client.ListFilesAsync(pagingRequest);
+```
+
+##### All Files (Multiple Pages)
+
+```csharp
+await foreach (var pageResult in client.ListAllFilesAsync(limit: 20))
+{
+    if (pageResult.IsSuccess)
+    {
+        var page = pageResult.Value;
+        foreach (var file in page.Data)
+        {
+            Console.WriteLine($"- {file.Name} (ID: {file.Id})");
+        }
+    }
+}
+```
+
+#### Get File Information
+
+Retrieve metadata about a specific file:
+
+```csharp
+var result = await client.GetFileInfoAsync("file_12345");
+
+if (result.IsSuccess)
+{
+    var file = result.Value;
+    Console.WriteLine($"File: {file.Name}");
+    Console.WriteLine($"ID: {file.Id}");
+    Console.WriteLine($"MIME Type: {file.MimeType}");
+    Console.WriteLine($"Size: {file.Size} bytes");
+    Console.WriteLine($"Created: {file.CreatedAt}");
+    Console.WriteLine($"Downloadable: {file.Downloadable}");
+}
+```
+
+#### Get File Content
+
+Download the content of a file as a stream:
+
+```csharp
+var result = await client.GetFileAsync("file_12345");
+
+if (result.IsSuccess)
+{
+    using var contentStream = result.Value;
+    using var reader = new StreamReader(contentStream);
+    var content = await reader.ReadToEndAsync();
+
+    Console.WriteLine("File content:");
+    Console.WriteLine(content);
+}
+```
+
+#### Delete a File
+
+Remove a file from your account:
+
+```csharp
+var result = await client.DeleteFileAsync("file_12345");
+
+if (result.IsSuccess)
+{
+    var deleteResponse = result.Value;
+    Console.WriteLine($"Deleted file: {deleteResponse.Id}");
+    Console.WriteLine($"Type: {deleteResponse.Type}");
+}
+```
+
+> [!NOTE]
+> The Files API has certain limitations on file size, supported file types, and usage quotas. Please refer to the [Anthropic API Documentation](https://docs.anthropic.com/en/docs/build-with-claude/files) for the most up-to-date information on these limitations.
+
 ### Create a message
 
 The `AnthropicApiClient` exposes a method named `CreateMessageAsync` that can be used to create a message. The method requires a `MessageRequest` or a `StreamMessageRequest` instance as a parameter. The `MessageRequest` class is used to create a message whose response is not streamed and the `StreamMessageRequest` class is used to create a message whose response is streamed. The `MessageRequest` instance's properties can be set to configure how the message is created.

src/AnthropicClient/AnthropicApiClient.cs

@@ -18,6 +18,7 @@ public class AnthropicApiClient : IAnthropicApiClient
   private string CountTokensEndpoint => $"{MessagesEndpoint}/count_tokens";
   private string MessageBatchesEndpoint => $"{MessagesEndpoint}/batches";
   private const string ModelsEndpoint = "models";
+  private const string FilesEndpoint = "files";
   private const string JsonContentType = "application/json";
   private const string EventPrefix = "event:";
   private const string DataPrefix = "data:";
@@ -380,6 +381,64 @@ public async Task<AnthropicResult<AnthropicModel>> GetModelAsync(string modelId,
     return await CreateResultAsync<AnthropicModel>(response);
   }
 
+  /// <inheritdoc/>
+  public async Task<AnthropicResult<AnthropicFile>> CreateFileAsync(CreateFileRequest request, CancellationToken cancellationToken = default)
+  {
+    var response = await SendFileRequestAsync(FilesEndpoint, request, cancellationToken);
+    return await CreateResultAsync<AnthropicFile>(response);
+  }
+
+  /// <inheritdoc/>
+  public async Task<AnthropicResult<Page<AnthropicFile>>> ListFilesAsync(PagingRequest? request = null, CancellationToken cancellationToken = default)
+  {
+    var pagingRequest = request ?? new PagingRequest();
+    var endpoint = $"{FilesEndpoint}?{pagingRequest.ToQueryParameters()}";
+    var response = await SendRequestAsync(endpoint, cancellationToken: cancellationToken);
+    return await CreateResultAsync<Page<AnthropicFile>>(response);
+  }
+
+  /// <inheritdoc/>
+  public async IAsyncEnumerable<AnthropicResult<Page<AnthropicFile>>> ListAllFilesAsync(int limit = 20, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+  {
+    await foreach (var result in GetAllPagesAsync<AnthropicFile>(FilesEndpoint, limit, cancellationToken))
+    {
+      yield return result;
+    }
+  }
+
+  /// <inheritdoc/>
+  public async Task<AnthropicResult<AnthropicFile>> GetFileInfoAsync(string fileId, CancellationToken cancellationToken = default)
+  {
+    var endpoint = $"{FilesEndpoint}/{fileId}";
+    var response = await SendRequestAsync(endpoint, cancellationToken: cancellationToken);
+    return await CreateResultAsync<AnthropicFile>(response);
+  }
+
+  /// <inheritdoc/>
+  public async Task<AnthropicResult<Stream>> GetFileAsync(string fileId, CancellationToken cancellationToken = default)
+  {
+    var endpoint = $"{FilesEndpoint}/{fileId}/content";
+    var response = await SendRequestAsync(endpoint, cancellationToken: cancellationToken);
+
+    if (response.IsSuccessStatusCode is false)
+    {
+      var content = await response.Content.ReadAsStringAsync();
+      var error = Deserialize<AnthropicError>(content) ?? new AnthropicError();
+      return AnthropicResult<Stream>.Failure(error, new AnthropicHeaders(response.Headers));
+    }
+
+    var stream = await response.Content.ReadAsStreamAsync();
+    return AnthropicResult<Stream>.Success(stream, new AnthropicHeaders(response.Headers));
+  }
+
+  /// <inheritdoc/>
+  public async Task<AnthropicResult<AnthropicFileDeleteResponse>> DeleteFileAsync(string fileId, CancellationToken cancellationToken = default)
+  {
+    var endpoint = $"{FilesEndpoint}/{fileId}";
+    var response = await SendRequestAsync(endpoint, HttpMethod.Delete, cancellationToken);
+    return await CreateResultAsync<AnthropicFileDeleteResponse>(response);
+  }
+
   private async IAsyncEnumerable<AnthropicResult<Page<T>>> GetAllPagesAsync<T>(string endpoint, int limit = 20, [EnumeratorCancellation] CancellationToken cancellationToken = default)
   {
     var pagingRequest = new PagingRequest(limit: limit);
@@ -462,6 +521,17 @@ private async Task<HttpResponseMessage> SendRequestAsync<T>(string endpoint, T r
     return await _httpClient.PostAsync(endpoint, requestContent, cancellationToken);
   }
 
+  private async Task<HttpResponseMessage> SendFileRequestAsync(string endpoint, CreateFileRequest request, CancellationToken cancellationToken = default)
+  {
+    using var multipartContent = new MultipartFormDataContent();
+
+    using var fileContent = new ByteArrayContent(request.File);
+    fileContent.Headers.ContentType = new MediaTypeHeaderValue(request.FileType);
+    multipartContent.Add(fileContent, "file", request.FileName);
+
+    return await _httpClient.PostAsync(endpoint, multipartContent, cancellationToken);
+  }
+
   private string Serialize<T>(T obj) => JsonSerializer.Serialize(obj, JsonSerializationOptions.DefaultOptions);
   private T? Deserialize<T>(string json) => JsonSerializer.Deserialize<T>(json, JsonSerializationOptions.DefaultOptions);
 }

src/AnthropicClient/IAnthropicApiClient.cs

@@ -111,4 +111,53 @@ public interface IAnthropicApiClient
   /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
   /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="AnthropicModel"/>.</returns>
   Task<AnthropicResult<AnthropicModel>> GetModelAsync(string modelId, CancellationToken cancellationToken = default);
+
+  /// <summary>
+  /// Creates a file asynchronously using the Files API.
+  /// </summary>
+  /// <param name="request">The file creation request.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="AnthropicFile"/>.</returns>
+  Task<AnthropicResult<AnthropicFile>> CreateFileAsync(CreateFileRequest request, CancellationToken cancellationToken = default);
+
+  /// <summary>
+  /// Lists files asynchronously, returning a single page of results.
+  /// </summary>
+  /// <param name="request">The paging request to use for listing the files.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="Page{T}"/> where T is <see cref="AnthropicFile"/>.</returns>
+  Task<AnthropicResult<Page<AnthropicFile>>> ListFilesAsync(PagingRequest? request = null, CancellationToken cancellationToken = default);
+
+  /// <summary>
+  /// Lists all files asynchronously, returning every page of results.
+  /// </summary>
+  /// <param name="limit">The maximum number of files to return in each page.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>An asynchronous enumerable that yields the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="Page{T}"/> where T is <see cref="AnthropicFile"/>.</returns>
+  IAsyncEnumerable<AnthropicResult<Page<AnthropicFile>>> ListAllFilesAsync(int limit = 20, CancellationToken cancellationToken = default);
+
+  /// <summary>
+  /// Gets a file's metadata by its ID asynchronously.
+  /// </summary>
+  /// <param name="fileId">The ID of the file to get.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="AnthropicFile"/>.</returns>
+  Task<AnthropicResult<AnthropicFile>> GetFileInfoAsync(string fileId, CancellationToken cancellationToken = default);
+
+  /// <summary>
+  /// Gets a file's content by its ID asynchronously.
+  /// </summary>
+  /// <param name="fileId">The ID of the file to get the content for.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is a stream containing the file content.</returns>
+  Task<AnthropicResult<Stream>> GetFileAsync(string fileId, CancellationToken cancellationToken = default);
+
+
+  /// <summary>
+  /// Deletes a file by its ID asynchronously.
+  /// </summary>
+  /// <param name="fileId">The ID of the file to delete.</param>
+  /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+  /// <returns>A task that represents the asynchronous operation. The task result contains the response as an <see cref="AnthropicResult{T}"/> where T is <see cref="AnthropicFileDeleteResponse"/>.</returns>
+  Task<AnthropicResult<AnthropicFileDeleteResponse>> DeleteFileAsync(string fileId, CancellationToken cancellationToken = default);
 }

src/AnthropicClient/Json/SourceConverter.cs

@@ -16,6 +16,8 @@ public override Source Read(ref Utf8JsonReader reader, Type typeToConvert, JsonS
     {
       SourceType.Text => JsonSerializer.Deserialize<TextSource>(root.GetRawText(), options)!,
       SourceType.Content => JsonSerializer.Deserialize<CustomSource>(root.GetRawText(), options)!,
+      SourceType.File => JsonSerializer.Deserialize<FileSource>(root.GetRawText(), options)!,
+      SourceType.Url => JsonSerializer.Deserialize<UrlSource>(root.GetRawText(), options)!,
       SourceType.Base64 => DeserializeBase64Source(root, options),
       _ => throw new JsonException($"Unknown source type: {type}")
     };
@@ -54,6 +56,18 @@ public override void Write(Utf8JsonWriter writer, Source value, JsonSerializerOp
       return;
     }
 
+    if (value is FileSource fileSource)
+    {
+      JsonSerializer.Serialize(writer, fileSource, options);
+      return;
+    }
+
+    if (value is UrlSource urlSource)
+    {
+      JsonSerializer.Serialize(writer, urlSource, options);
+      return;
+    }
+
     JsonSerializer.Serialize(writer, value, value.GetType(), options);
   }
 }

src/AnthropicClient/Models/AnthropicFile.cs

@@ -0,0 +1,51 @@
+using System.Text.Json.Serialization;
+
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Represents a file object from the Anthropic Files API.
+/// </summary>
+public class AnthropicFile
+{
+  /// <summary>
+  /// Unique object identifier.
+  /// </summary>
+  [JsonPropertyName("id")]
+  public string Id { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Object type.
+  /// </summary>
+  [JsonPropertyName("type")]
+  public string Type { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Original filename of the uploaded file.
+  /// </summary>
+  [JsonPropertyName("filename")]
+  public string Name { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Date file was created.
+  /// </summary>
+  [JsonPropertyName("created_at")]
+  public DateTimeOffset CreatedAt { get; init; }
+
+  /// <summary>
+  /// Size of the file in bytes.
+  /// </summary>
+  [JsonPropertyName("size_bytes")]
+  public long Size { get; init; }
+
+  /// <summary>
+  /// MIME type of the file.
+  /// </summary>
+  [JsonPropertyName("mime_type")]
+  public string MimeType { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Whether the file can be downloaded.
+  /// </summary>
+  [JsonPropertyName("downloadable")]
+  public bool Downloadable { get; init; }
+}

src/AnthropicClient/Models/AnthropicFileDeleteResponse.cs

@@ -0,0 +1,17 @@
+namespace AnthropicClient.Models;
+
+/// <summary>
+/// Represents the response from deleting a file in the Anthropic API.
+/// </summary>
+public class AnthropicFileDeleteResponse
+{
+  /// <summary>
+  /// Gets or sets the ID of the file that was deleted.
+  /// </summary>
+  public string Id { get; init; } = string.Empty;
+
+  /// <summary>
+  /// Gets or sets the response type
+  /// </summary>
+  public string Type { get; init; } = string.Empty;
+}