anthropic/http

HTTP types and request/response builders for sans-io pattern

This module provides HTTP-library-agnostic types for building requests and parsing responses. Users can use any HTTP client by:

Building a request with build_messages_request
Sending it with their preferred HTTP client
Parsing the response with parse_messages_response

Example with custom HTTP client

import anthropic/http
import anthropic/types/request
import anthropic/types/message.{user_message}

// Build the request
let api_request = request.new(
  "claude-sonnet-4-20250514",
  [user_message("Hello!")],
  1024,
)
let http_request = http.build_messages_request(config, api_request)

// Send with your HTTP client (e.g., hackney, httpc, fetch on JS)
let http_response = my_http_client.send(http_request)

// Parse the response
case http.parse_messages_response(http_response) {
  Ok(response) -> io.println(request.response_text(response))
  Error(err) -> io.println(error.error_to_string(err))
}

Types

HttpRequest

</>

HTTP request representation (HTTP-library agnostic)

pub type HttpRequest {
  HttpRequest(
    method: Method,
    url: String,
    headers: List(#(String, String)),
    body: String,
  )
}

Constructors

```
HttpRequest(
  method: Method,
  url: String,
  headers: List(#(String, String)),
  body: String,
)
```
Arguments

method

HTTP method

url

Full URL including base URL and path

headers

Request headers as key-value pairs

body

Request body (JSON string)

HttpResponse

</>

HTTP response representation (HTTP-library agnostic)

pub type HttpResponse {
  HttpResponse(
    status: Int,
    headers: List(#(String, String)),
    body: String,
  )
}

Constructors

HttpResponse(
  status: Int,
  headers: List(#(String, String)),
  body: String,
)

Arguments

status: HTTP status code
headers: Response headers as key-value pairs
body: Response body

Method

</>

HTTP method

pub type Method {
  Get
  Post
  Put
  Delete
  Patch
}

Constructors

```
Get
```
```
Post
```
```
Put
```
```
Delete
```
```
Patch
```

Values

api_version

</>

pub const api_version: String

Current Anthropic API version header value

build_messages_request

</>

pub fn build_messages_request(
  api_key: String,
  base_url: String,
  message_request: request.CreateMessageRequest,
) -> HttpRequest

Build an HTTP request for the Messages API

This function creates an HTTP-library-agnostic request that can be sent using any HTTP client. It handles:

URL construction
Authentication headers
Content-Type and API version headers
JSON body encoding

Example

let req = request.new("claude-sonnet-4-20250514", messages, 1024)
let http_req = build_messages_request("sk-ant-...", default_base_url, req)
// Send http_req with your HTTP client

build_streaming_request

</>

pub fn build_streaming_request(
  api_key: String,
  base_url: String,
  message_request: request.CreateMessageRequest,
) -> HttpRequest

Build an HTTP request for streaming Messages API

Similar to build_messages_request but adds the Accept header for SSE and ensures the stream flag is set on the request.

check_status

</>

pub fn check_status(
  response: HttpResponse,
) -> Result(String, error.AnthropicError)

Check HTTP status and extract body or error

default_base_url

</>

pub const default_base_url: String

Default Anthropic API base URL

messages_endpoint

</>

pub const messages_endpoint: String

Messages API endpoint path

method_to_string

</>

pub fn method_to_string(method: Method) -> String

Convert Method to string for HTTP libraries that need it

parse_messages_response

</>

pub fn parse_messages_response(
  response: HttpResponse,
) -> Result(request.CreateMessageResponse, error.AnthropicError)

Parse an HTTP response into a CreateMessageResponse

This function handles:

Status code checking (success vs error)
Error response parsing with proper error types
Success response JSON decoding

Example

let http_response = HttpResponse(status: 200, headers: [], body: json_body)
case parse_messages_response(http_response) {
  Ok(response) -> handle_success(response)
  Error(err) -> handle_error(err)
}

parse_response_body

</>

pub fn parse_response_body(
  body: String,
) -> Result(request.CreateMessageResponse, error.AnthropicError)

Parse successful response body into CreateMessageResponse

validate_request

</>

pub fn validate_request(
  req: request.CreateMessageRequest,
) -> Result(Nil, error.AnthropicError)

Validate a CreateMessageRequest before sending

This performs client-side validation to catch errors early. Delegates to the shared validation module for consistent validation rules.