> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rowboatlabs/rowboat/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete Python SDK API documentation

## Client

The main interface for interacting with the Rowboat API.

### Constructor

Create a new client instance:

```python theme={null}
from rowboat.client import Client

client = Client(
    host="https://api.rowboat.dev",
    projectId="your-project-id",
    apiKey="your-api-key"
)
```

#### Parameters

**host** `string` *required*

The Rowboat API host URL (e.g., `https://api.rowboat.dev`)

**projectId** `string` *required*

Your Rowboat project ID from the dashboard

**apiKey** `string` *required*

Your Rowboat API key for authentication

### Methods

#### run\_turn()

Execute a single conversation turn with the agent.

```python theme={null}
result = client.run_turn(
    messages=[UserMessage(role='user', content="Hello!")],
    conversationId="conv_123",
    mockTools={"tool_name": "mock response"}
)
```

##### Parameters

**messages** `List[ApiMessage]` *required*

List of messages to send to the agent. Must include at least one message.

Supported message types:

* `UserMessage`
* `SystemMessage`
* `AssistantMessage`
* `AssistantMessageWithToolCalls`
* `ToolMessage`

**conversationId** `string`

The conversation ID from a previous turn. Omit to start a new conversation.

Used to maintain context across multiple turns in a conversation.

**mockTools** `Dict[str, str]`

Dictionary mapping tool names to mock responses.

Use this to test agent behavior without executing real tools:

```python theme={null}
mockTools={
    "weather_lookup": "Sunny and 72°F",
    "calculator": "42"
}
```

##### Returns

**ApiResponse** `object`

The API response containing the conversation ID and turn output.

**conversationId** `string`

The conversation ID. Use this for subsequent turns to maintain context.

**turn** `Turn`

The turn object containing the agent's response.

**id** `string`

Unique identifier for this turn.

**output** `List[ApiMessage]`

List of output messages from the agent. The last message typically contains the agent's response.

##### Raises

* `ValueError`: Raised when the API returns a non-200 status code

##### Example

```python theme={null}
try:
    result = client.run_turn(
        messages=[UserMessage(role='user', content="Hello")]
    )
    print(result.turn.output[-1].content)
    print("Conversation ID:", result.conversationId)
except ValueError as e:
    print(f"API Error: {e}")
```

## Message Types

All message types are imported from `rowboat.schema`.

### UserMessage

Represents a message from the end user.

```python theme={null}
from rowboat.schema import UserMessage

message = UserMessage(
    role='user',
    content="What's the weather today?"
)
```

#### Fields

**role** `Literal['user']` *required*

Must be `'user'`

**content** `string` *required*

The message content from the user

### SystemMessage

Provides system instructions or context to the agent.

```python theme={null}
from rowboat.schema import SystemMessage

message = SystemMessage(
    role='system',
    content="You are a helpful weather assistant."
)
```

#### Fields

**role** `Literal['system']` *required*

Must be `'system'`

**content** `string` *required*

The system instruction or context

### AssistantMessage

Represents a response from the agent.

```python theme={null}
from rowboat.schema import AssistantMessage

message = AssistantMessage(
    role='assistant',
    content="The weather is sunny and 72°F.",
    responseType='external',
    agenticName='weather-bot'
)
```

#### Fields

**role** `Literal['assistant']` *required*

Must be `'assistant'`

**content** `string` *required*

The assistant's response message

**responseType** `Literal['internal', 'external']` *required*

The type of response:

* `'internal'`: Internal agent reasoning (not shown to user)
* `'external'`: User-facing response

**agenticName** `string`

Optional name identifier for the agent

### AssistantMessageWithToolCalls

Represents an assistant message that includes tool calls.

```python theme={null}
from rowboat.schema import AssistantMessageWithToolCalls, ToolCall, FunctionCall

message = AssistantMessageWithToolCalls(
    role='assistant',
    content="Let me check the weather for you.",
    toolCalls=[
        ToolCall(
            id='call_123',
            type='function',
            function=FunctionCall(
                name='weather_lookup',
                arguments='{"city": "San Francisco"}'
            )
        )
    ],
    agenticName='weather-bot'
)
```

#### Fields

**role** `Literal['assistant']` *required*

Must be `'assistant'`

**content** `string`

Optional message content

**toolCalls** `List[ToolCall]` *required*

List of tool calls made by the assistant

**agenticName** `string`

Optional name identifier for the agent

### ToolMessage

Represents the result of a tool execution.

```python theme={null}
from rowboat.schema import ToolMessage

message = ToolMessage(
    role='tool',
    content='{"temperature": 72, "condition": "sunny"}',
    toolCallId='call_123',
    toolName='weather_lookup'
)
```

#### Fields

**role** `Literal['tool']` *required*

Must be `'tool'`

**content** `string` *required*

The tool execution result (typically JSON string)

**toolCallId** `string` *required*

The ID of the tool call this message responds to

**toolName** `string` *required*

The name of the tool that was executed

## Type Definitions

### ToolCall

Represents a request to execute a tool.

```python theme={null}
from rowboat.schema import ToolCall, FunctionCall

tool_call = ToolCall(
    id='call_123',
    type='function',
    function=FunctionCall(
        name='weather_lookup',
        arguments='{"city": "San Francisco"}'
    )
)
```

#### Fields

**id** `string` *required*

Unique identifier for this tool call

**type** `Literal['function']` *required*

Must be `'function'`

**function** `FunctionCall` *required*

The function call details

### FunctionCall

Contains details about a function to be called.

```python theme={null}
from rowboat.schema import FunctionCall

function_call = FunctionCall(
    name='weather_lookup',
    arguments='{"city": "San Francisco"}'
)
```

#### Fields

**name** `string` *required*

The name of the function to call

**arguments** `string` *required*

JSON string containing the function arguments

### Turn

Represents a single conversation turn.

```python theme={null}
from rowboat.schema import Turn

turn = Turn(
    id='turn_123',
    output=[AssistantMessage(...)]
)
```

#### Fields

**id** `string` *required*

Unique identifier for this turn

**output** `List[ApiMessage]` *required*

List of messages generated during this turn

### ApiRequest

The request payload sent to the API.

```python theme={null}
from rowboat.schema import ApiRequest

request = ApiRequest(
    conversationId='conv_123',
    messages=[UserMessage(role='user', content='Hello')],
    mockTools={'tool': 'response'}
)
```

#### Fields

**conversationId** `string`

Optional conversation ID to continue an existing conversation

**messages** `List[ApiMessage]` *required*

List of messages to send

**mockTools** `Dict[str, str]`

Optional mock tool responses for testing

### ApiResponse

The response received from the API.

```python theme={null}
from rowboat.schema import ApiResponse

response = ApiResponse(
    conversationId='conv_123',
    turn=Turn(...)
)
```

#### Fields

**conversationId** `string` *required*

The conversation ID (use for subsequent turns)

**turn** `Turn` *required*

The turn data containing the agent's response

## Complete Example

Here's a comprehensive example using the full API:

```python theme={null}
from rowboat.client import Client
from rowboat.schema import (
    UserMessage,
    SystemMessage,
    ApiResponse
)
import os

# Initialize client
client = Client(
    host=os.getenv("ROWBOAT_HOST", "https://api.rowboat.dev"),
    projectId=os.getenv("ROWBOAT_PROJECT_ID"),
    apiKey=os.getenv("ROWBOAT_API_KEY")
)

def chat(user_message: str, conversation_id: str = None) -> ApiResponse:
    """Send a message and return the response."""
    try:
        result = client.run_turn(
            messages=[
                SystemMessage(
                    role='system',
                    content='You are a helpful assistant.'
                ),
                UserMessage(
                    role='user',
                    content=user_message
                )
            ],
            conversationId=conversation_id
        )
        return result
    except ValueError as e:
        print(f"API Error: {e}")
        raise

# Start conversation
result = chat("What can you help me with?")
print("Assistant:", result.turn.output[-1].content)
conv_id = result.conversationId

# Continue conversation
result = chat("Tell me about your capabilities.", conv_id)
print("Assistant:", result.turn.output[-1].content)
```

## Error Handling

The SDK raises `ValueError` when the API returns an error:

```python theme={null}
try:
    result = client.run_turn(
        messages=[UserMessage(role='user', content='Hello')]
    )
except ValueError as e:
    # Handle API errors
    print(f"Error: {e}")
    # Error format: "Error: {status_code} - {response_text}"
```

Common error scenarios:

* **401 Unauthorized**: Invalid API key
* **404 Not Found**: Invalid project ID or endpoint
* **429 Too Many Requests**: Rate limit exceeded
* **500 Internal Server Error**: Server-side error

## Type Safety

All classes use Pydantic for runtime type validation:

```python theme={null}
from pydantic import ValidationError
from rowboat.schema import UserMessage

try:
    # This will raise a ValidationError
    message = UserMessage(role='invalid', content='Hello')
except ValidationError as e:
    print(e)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.