anthropic/api

API functions for Anthropic Messages API

This module provides the core functions for interacting with Claude’s Messages API, including message creation and response parsing.

Quick Start

For most use cases, use the unified chat functions:

import anthropic/api
import anthropic/client
import anthropic/types/request
import anthropic/types/message.{user_message}

// Initialize client
let assert Ok(client) = client.init()

// Create a request
let req = request.new(
  "claude-sonnet-4-20250514",
  [user_message("Hello, Claude!")],
  1024,
)

// Non-streaming chat
case api.chat(client, req) {
  Ok(response) -> io.println(request.response_text(response))
  Error(err) -> io.println(error.error_to_string(err))
}

// Streaming chat (batch mode - collects all events)
case api.chat_stream(client, req) {
  Ok(result) -> io.println(api.stream_text(result))
  Error(err) -> io.println(error.error_to_string(err))
}

Types

EventCallback

</>

Callback function type for processing streaming events

pub type EventCallback =
  fn(streaming.StreamEvent) -> Nil

StreamError

</>

Error during streaming

pub type StreamError {
  HttpError(error: error.AnthropicError)
  SseParseError(message: String)
  EventDecodeError(message: String)
  ApiError(status: Int, body: String)
}

Constructors

```
HttpError(error: error.AnthropicError)
```
HTTP-level error during request
```
SseParseError(message: String)
```
Error parsing SSE data
```
EventDecodeError(message: String)
```
Error decoding event JSON
```
ApiError(status: Int, body: String)
```
API returned an error response

StreamResult

</>

Result of a streaming chat request

pub type StreamResult {
  StreamResult(events: List(streaming.StreamEvent))
}

Constructors

StreamResult(events: List(streaming.StreamEvent))

Arguments

events: List of parsed streaming events

Values

chat

</>

pub fn chat(
  client: client.Client,
  message_request: request.CreateMessageRequest,
) -> Result(request.CreateMessageResponse, error.AnthropicError)

Send a chat message and receive a response (non-streaming)

This is the primary function for interacting with Claude. It sends a message and returns the complete response.

Example

import anthropic/api
import anthropic/client
import anthropic/types/request
import anthropic/types/message.{user_message}

let assert Ok(client) = client.init()
let req = request.new(
  "claude-sonnet-4-20250514",
  [user_message("What is the capital of France?")],
  1024,
)

case api.chat(client, req) {
  Ok(response) -> io.println(request.response_text(response))
  Error(err) -> handle_error(err)
}

chat_stream

</>

pub fn chat_stream(
  client: client.Client,
  message_request: request.CreateMessageRequest,
) -> Result(StreamResult, StreamError)

Send a chat message with streaming response (batch mode)

This function sends a message and returns all streaming events after the response completes. For true real-time streaming, use the sans-io functions in anthropic/streaming/handler.

Example

import anthropic/api
import anthropic/client
import anthropic/types/request
import anthropic/types/message.{user_message}

let assert Ok(client) = client.init()
let req = request.new(
  "claude-sonnet-4-20250514",
  [user_message("Tell me a story")],
  2048,
)

case api.chat_stream(client, req) {
  Ok(result) -> io.println(api.stream_text(result))
  Error(err) -> handle_stream_error(err)
}

chat_stream_with_callback

</>

pub fn chat_stream_with_callback(
  client: client.Client,
  message_request: request.CreateMessageRequest,
  callback: fn(streaming.StreamEvent) -> Nil,
) -> Result(StreamResult, StreamError)

Send a streaming chat message with a callback for each event

Note: Despite the callback, this function collects ALL events before calling the callbacks. It does NOT provide true real-time streaming. For real-time streaming, use the sans-io functions in anthropic/streaming/handler.

Example

api.chat_stream_with_callback(client, request, fn(event) {
  case api.event_text(event) {
    Ok(text) -> io.print(text)
    Error(_) -> Nil
  }
})

create_message

</>

pub fn create_message(
  client: client.Client,
  message_request: request.CreateMessageRequest,
) -> Result(request.CreateMessageResponse, error.AnthropicError)

Deprecated: Use api.chat instead

Create a message using the Anthropic Messages API

@deprecated Use api.chat instead for a more intuitive API

Example

// Prefer using api.chat instead:
case api.chat(client, request) {
  Ok(response) -> io.println(response_text(response))
  Error(err) -> io.println(error_to_string(err))
}

event_text

</>

pub fn event_text(
  event: streaming.StreamEvent,
) -> Result(String, Nil)

Extract text from a single streaming event

Example

list.each(result.events, fn(event) {
  case api.event_text(event) {
    Ok(text) -> io.print(text)
    Error(_) -> Nil
  }
})

stream_complete

</>

pub fn stream_complete(result: StreamResult) -> Bool

Check if a streaming result completed successfully

stream_has_error

</>

pub fn stream_has_error(result: StreamResult) -> Bool

Check if a streaming result contains an error

stream_message_id

</>

pub fn stream_message_id(
  result: StreamResult,
) -> Result(String, Nil)

Get the message ID from a streaming result

stream_model

</>

pub fn stream_model(result: StreamResult) -> Result(String, Nil)

Get the model from a streaming result

stream_text

</>

pub fn stream_text(result: StreamResult) -> String

Get the full text from a streaming result

Example

case api.chat_stream(client, request) {
  Ok(result) -> io.println(api.stream_text(result))
  Error(_) -> io.println("Error")
}