Braintrust.Client (Braintrust v0.3.0)

HTTP client for the Braintrust API.

This module handles all HTTP communication with the Braintrust API, including authentication, JSON encoding/decoding, timeouts, and automatic retry with exponential backoff.

Usage

The client is typically used internally by resource modules, but can be used directly for custom API calls:

# Create a client
client = Braintrust.Client.new(api_key: "sk-...")

# Make requests
{:ok, body} = Braintrust.Client.get(client, "/v1/project")
{:ok, body} = Braintrust.Client.post(client, "/v1/project", %{name: "my-project"})

Retry Behavior

The client automatically retries requests that fail with:

408 Request Timeout
409 Conflict
429 Rate Limit (respects Retry-After header)
5xx Server Errors
Connection/timeout errors

Default: 2 retries with exponential backoff (1s, 2s, 4s).

Summary

Types

t()

Functions

delete(client, path, opts \\ [])

Makes a DELETE request.

get(client, path, opts \\ [])

Makes a GET request.

get_all(client, path, opts \\ [])

Makes a paginated GET request, returning all items as a list.

get_stream(client, path, opts \\ [])

Makes a paginated GET request, returning a Stream of items.

new(opts \\ [])

Creates a new HTTP client.

patch(client, path, body, opts \\ [])

Makes a PATCH request.

post(client, path, body, opts \\ [])

Makes a POST request.

Types

t()

@type t() :: Req.Request.t()

Functions

delete(client, path, opts \\ [])

@spec delete(t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Braintrust.Error.t()}

Makes a DELETE request.

Examples

client = Braintrust.Client.new(api_key: "sk-test")
{:ok, _} = Braintrust.Client.delete(client, "/v1/project/123")

get(client, path, opts \\ [])

@spec get(t(), String.t(), keyword()) ::
  {:ok, map() | list()} | {:error, Braintrust.Error.t()}

Makes a GET request.

Examples

client = Braintrust.Client.new(api_key: "sk-test")
{:ok, projects} = Braintrust.Client.get(client, "/v1/project")

get_all(client, path, opts \\ [])

@spec get_all(t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, Braintrust.Error.t()}

Makes a paginated GET request, returning all items as a list.

This is a convenience wrapper around Braintrust.Pagination.list/2. For large datasets, prefer get_stream/3.

Options

Same as get_stream/3.

Examples

client = Braintrust.Client.new(api_key: "sk-test")
{:ok, projects} = Braintrust.Client.get_all(client, "/v1/project")

get_stream(client, path, opts \\ [])

@spec get_stream(t(), String.t(), keyword()) :: Enumerable.t()

Makes a paginated GET request, returning a Stream of items.

This is a convenience wrapper around Braintrust.Pagination.stream/2 for paginating through list endpoints.

Options

:limit - Number of items per page (default: 100)
:starting_after - Cursor to start pagination from
:unique_by - Key for duplicate filtering
:params - Additional query parameters

Examples

client = Braintrust.Client.new(api_key: "sk-test")

client
|> Braintrust.Client.get_stream("/v1/project", limit: 50)
|> Stream.take(100)
|> Enum.to_list()

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new HTTP client.

Options

All options from Braintrust.Config are supported:

:api_key - API key for authentication
:base_url - Base URL for API requests
:timeout - Request timeout in milliseconds
:max_retries - Maximum number of retry attempts

Examples

iex> client = Braintrust.Client.new(api_key: "sk-test123")
iex> is_struct(client, Req.Request)
true

patch(client, path, body, opts \\ [])

@spec patch(t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Braintrust.Error.t()}

Makes a PATCH request.

Examples

client = Braintrust.Client.new(api_key: "sk-test")
{:ok, project} = Braintrust.Client.patch(client, "/v1/project/123", %{name: "new-name"})

post(client, path, body, opts \\ [])

@spec post(t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Braintrust.Error.t()}

Makes a POST request.

Examples

client = Braintrust.Client.new(api_key: "sk-test")
{:ok, project} = Braintrust.Client.post(client, "/v1/project", %{name: "my-project"})