API Reference

Complete reference documentation for all classes, methods, and exceptions in the Claro Python SDK.

BaytClient

The main client class for interacting with the Claro API.

Constructor

BaytClient(
    api_key: Optional[str] = None,
    base_url: str = "https://api.baytos.ai",
    max_retries: int = 3
)

Parameters:

Name	Type	Default	Description
`api_key`	`str \| None`	`None`	API key. If not provided, reads from `BAYT_API_KEY` environment variable
`base_url`	`str`	`"https://api.baytos.ai"`	Base URL for the API
`max_retries`	`int`	`3`	Maximum number of retry attempts for rate-limited requests

Raises:

ValueError - If no API key is provided and BAYT_API_KEY is not set
ValueError - If API key format is invalid (must start with sk_)

Example:

from baytos.claro import BaytClient

# Using environment variable
client = BaytClient()

# With explicit API key
client = BaytClient(api_key="your_api_key")

# Custom configuration
client = BaytClient(
    api_key="your_api_key",
    base_url="https://staging-api.baytos.ai",
    max_retries=5
)

get_prompt()

Fetch a prompt by its package name.

get_prompt(package_name: str) -> Prompt

Parameters:

Name	Type	Description
`package_name`	`str`	Package identifier (e.g., `"@workspace/my-prompt:v1"`)

Returns:

Prompt - Prompt object with content and metadata

Raises:

BaytValidationError - If package name format is invalid
BaytAuthError - If authentication fails (401, 403)
BaytNotFoundError - If prompt is not found (404)
BaytRateLimitError - If rate limit is exceeded after retries (429)
BaytAPIError - For other API errors

Example:

prompt = client.get_prompt("@workspace/support:v1")
print(prompt.title)
print(prompt.generator)

list_prompts()

List prompts accessible to the authenticated user.

list_prompts(
    limit: int = 20,
    cursor: Optional[str] = None
) -> Dict[str, Any]

Parameters:

Name	Type	Default	Description
`limit`	`int`	`20`	Maximum number of prompts to return (1-100)
`cursor`	`str \| None`	`None`	Pagination cursor from previous response

Returns: Dictionary with the following keys:

prompts (List[Prompt]) - List of Prompt objects
cursor (str) - Cursor for next page
hasMore (bool) - True if more pages available

Raises:

BaytValidationError - If limit is not between 1 and 100
BaytAuthError - If authentication fails
BaytRateLimitError - If rate limit is exceeded
BaytAPIError - For other API errors

Example:

# First page
result = client.list_prompts(limit=20)

for prompt in result['prompts']:
    print(prompt.title)

# Next page
if result['hasMore']:
    next_page = client.list_prompts(limit=20, cursor=result['cursor'])

download_context_file()

Download a context file and return its content as bytes.

download_context_file(context_id: str) -> bytes

Parameters:

Name	Type	Description
`context_id`	`str`	Context item ID from `prompt.context`

Returns:

bytes - File content

Raises:

BaytAuthError - If authentication fails
BaytNotFoundError - If context item is not found
BaytValidationError - If context item is not a file type
BaytAPIError - For other API errors

Example:

prompt = client.get_prompt("@workspace/research:v1")
files = prompt.get_file_contexts()

if files:
    content = client.download_context_file(files[0].id)
    with open(files[0].file_name, 'wb') as f:
        f.write(content)

get_context_download_url()

Get a signed download URL for a context file.

get_context_download_url(context_id: str) -> Dict[str, Any]

Parameters:

Name	Type	Description
`context_id`	`str`	Context item ID from `prompt.context`

Returns: Dictionary with the following keys:

url (str) - Signed download URL
expiresIn (int) - Seconds until URL expires

Raises:

BaytAuthError - If authentication fails
BaytNotFoundError - If context item is not found
BaytValidationError - If context item is not a file type
BaytAPIError - For other API errors

Example:

files = prompt.get_file_contexts()

if files:
    url_info = client.get_context_download_url(files[0].id)
    print(f"Download URL: {url_info['url']}")
    print(f"Expires in: {url_info['expiresIn']} seconds")

Prompt

Represents a Claro prompt with all its content and metadata.

Properties

Property	Type	Description
`id`	`str`	Unique prompt identifier
`title`	`str`	Human-readable title
`description`	`str \| None`	Optional description
`generator`	`str`	Main prompt content
`content`	`str`	Alias for `generator`
`system`	`str`	System prompt (may be empty)
`critique`	`str`	Critique prompt (may be empty)
`namespace`	`str`	Workspace slug
`slug`	`str`	Prompt slug
`version`	`str`	Version string (e.g., “v1”)
`package_name`	`str`	Full package name
`is_draft`	`bool`	True if version is v0
`category`	`str`	Prompt category
`context`	`List[ContextItem]`	Attached context items

Methods

has_context()

Check if the prompt has any context items.

has_context() -> bool

Returns:

bool - True if prompt has context items

Example:

if prompt.has_context():
    print("Prompt has attachments")

has_system_prompt()

Check if the prompt has a system prompt.

has_system_prompt() -> bool

Returns:

bool - True if prompt has a system prompt

has_critique_prompt()

Check if the prompt has a critique prompt.

has_critique_prompt() -> bool

Returns:

bool - True if prompt has a critique prompt

get_file_contexts()

Get only file-type context items.

get_file_contexts() -> List[ContextItem]

Returns:

List[ContextItem] - List of file context items

Example:

files = prompt.get_file_contexts()
for file in files:
    print(f"{file.file_name} ({file.file_size} bytes)")

get_url_contexts()

Get only URL-type context items.

get_url_contexts() -> List[ContextItem]

Returns:

List[ContextItem] - List of URL context items

Example:

urls = prompt.get_url_contexts()
for url in urls:
    print(url.url)

extract_variables()

Extract variables from prompt content with optional type hints.

extract_variables() -> List[Dict[str, str]]

Returns: List of dictionaries with the following keys:

name (str) - Variable name
type (str, optional) - Variable type
description (str, optional) - Variable description

Example:

variables = prompt.extract_variables()

for var in variables:
    print(f"Name: {var['name']}")
    if 'type' in var:
        print(f"Type: {var['type']}")

validate_variables()

Validate provided variables against expected variables.

validate_variables(provided_variables: Dict[str, Any]) -> Dict[str, str]

Parameters:

Name	Type	Description
`provided_variables`	`Dict[str, Any]`	Variable names and values

Returns:

Dict[str, str] - Validation errors (empty if all valid)

Example:

values = {
    'user_name': 'Alice',
    'count': 42
}

errors = prompt.validate_variables(values)

if errors:
    for field, message in errors.items():
        print(f"{field}: {message}")

to_dict()

Get the full dictionary representation of the prompt.

to_dict() -> Dict[str, Any]

Returns:

Dict[str, Any] - Dictionary representation

Dictionary-Style Access

Prompts support dictionary-style access:

# Get field
title = prompt['title']

# Get with default
desc = prompt.get('description', 'No description')

# Check if field exists
if 'system' in prompt:
    print(prompt['system'])

# Get all keys
keys = prompt.keys()

# Get all values
values = prompt.values()

# Get all items
items = prompt.items()

ContextItem

Represents a context item (file or URL) attached to a prompt.

Properties

Property	Type	Description
`id`	`str`	Unique context item identifier
`type`	`"file" \| "url"`	Context item type
`label`	`str \| None`	Optional label
`created_at`	`int \| None`	Unix timestamp when created
`file_name`	`str \| None`	File name (files only)
`file_size`	`int \| None`	File size in bytes (files only)
`mime_type`	`str \| None`	MIME type (files only)
`url`	`str \| None`	URL (URLs only)
`url_fetched_at`	`int \| None`	Unix timestamp when URL was fetched (URLs only)

Methods

is_file()

Check if this context item is a file.

is_file() -> bool

Returns:

bool - True if type is “file”

is_url()

Check if this context item is a URL.

is_url() -> bool

Returns:

bool - True if type is “url”

to_dict()

Get the full dictionary representation of the context item.

to_dict() -> Dict[str, Any]

Returns:

Dict[str, Any] - Dictionary representation

Example:

for item in prompt.context:
    if item.is_file():
        print(f"File: {item.file_name} ({item.file_size} bytes)")
    elif item.is_url():
        print(f"URL: {item.url}")

Exceptions

All exceptions inherit from BaytAPIError.

BaytAPIError

Base exception for all SDK errors.

class BaytAPIError(Exception)

Usage:

from baytos.claro import BaytAPIError

try:
    prompt = client.get_prompt("@workspace/test:v1")
except BaytAPIError as e:
    print(f"SDK error: {e}")

BaytAuthError

Authentication or authorization error (HTTP 401, 403).

class BaytAuthError(BaytAPIError)

Common causes:

Invalid API key
Expired API key
Insufficient permissions
Workspace access denied

Usage:

from baytos.claro import BaytAuthError

try:
    prompt = client.get_prompt("@workspace/test:v1")
except BaytAuthError:
    print("Authentication failed - check your API key")

BaytNotFoundError

Resource not found error (HTTP 404).

class BaytNotFoundError(BaytAPIError)

Common causes:

Incorrect package name
Wrong version number
Prompt deleted
No access to workspace

Usage:

from baytos.claro import BaytNotFoundError

try:
    prompt = client.get_prompt("@workspace/test:v1")
except BaytNotFoundError:
    print("Prompt not found")

BaytRateLimitError

Rate limit exceeded error (HTTP 429).

class BaytRateLimitError(BaytAPIError)

Raised only after all automatic retries are exhausted. Usage:

from baytos.claro import BaytRateLimitError
import time

try:
    prompt = client.get_prompt("@workspace/test:v1")
except BaytRateLimitError:
    print("Rate limited - waiting before retry")
    time.sleep(60)

BaytValidationError

Invalid request parameters (HTTP 400).

class BaytValidationError(BaytAPIError)

Common causes:

Invalid package name format
Out of range parameters
Missing required fields

Usage:

from baytos.claro import BaytValidationError

try:
    result = client.list_prompts(limit=200)  # Invalid
except BaytValidationError as e:
    print(f"Validation error: {e}")

Type Hints

The SDK is fully typed. Import types for type checking:

from typing import Dict, List, Any, Optional
from baytos.claro import BaytClient, Prompt, ContextItem

def process_prompt(client: BaytClient, package_name: str) -> Prompt:
    """Fetch and process a prompt"""
    prompt: Prompt = client.get_prompt(package_name)

    files: List[ContextItem] = prompt.get_file_contexts()

    for file in files:
        content: bytes = client.download_context_file(file.id)
        # Process file...

    return prompt

Complete Example

#!/usr/bin/env python3
"""
Complete API reference example showing all main features
"""

import os
from baytos.claro import (
    BaytClient,
    BaytAuthError,
    BaytNotFoundError,
    BaytAPIError
)

def main():
    # Initialize client
    client = BaytClient(
        api_key=os.getenv("BAYT_API_KEY"),
        max_retries=3
    )

    try:
        # Get a prompt
        prompt = client.get_prompt("@workspace/support:v1")

        # Access properties
        print(f"Title: {prompt.title}")
        print(f"Version: {prompt.version}")
        print(f"Package: {prompt.package_name}")

        # Content
        print(f"\nGenerator:\n{prompt.generator[:200]}...")

        if prompt.has_system_prompt():
            print(f"\nSystem:\n{prompt.system[:200]}...")

        # Variables
        variables = prompt.extract_variables()
        if variables:
            print(f"\nVariables: {len(variables)}")
            for var in variables:
                print(f"  - {var['name']}")

        # Context
        if prompt.has_context():
            files = prompt.get_file_contexts()
            urls = prompt.get_url_contexts()

            print(f"\nContext: {len(files)} files, {len(urls)} URLs")

            # Download first file
            if files:
                file = files[0]
                content = client.download_context_file(file.id)
                print(f"Downloaded: {file.file_name} ({len(content)} bytes)")

        # List prompts
        result = client.list_prompts(limit=10)
        print(f"\nTotal prompts: {len(result['prompts'])}")

    except BaytAuthError:
        print("Authentication failed")
    except BaytNotFoundError:
        print("Prompt not found")
    except BaytAPIError as e:
        print(f"API error: {e}")

if __name__ == "__main__":
    main()

Next Steps

Quickstart

Get started with the SDK

Working with Prompts

Learn about prompts in detail

Error Handling

Handle errors gracefully

Advanced Features

Optimize performance

Getting Started

Python SDK

Examples

Guides

Documentation Index

​API Reference

​BaytClient

​Constructor

​get_prompt()

​list_prompts()

​download_context_file()

​get_context_download_url()

​Prompt

​Properties

​Methods

​has_context()

​has_system_prompt()

​has_critique_prompt()

​get_file_contexts()

​get_url_contexts()

​extract_variables()

​validate_variables()

​to_dict()

​Dictionary-Style Access

​ContextItem

​Properties

​Methods

​is_file()

​is_url()

​to_dict()

​Exceptions

​BaytAPIError

​BaytAuthError

​BaytNotFoundError

​BaytRateLimitError

​BaytValidationError

​Type Hints

​Complete Example

​Next Steps

Quickstart

Working with Prompts

Error Handling

Advanced Features

API Reference

BaytClient

Constructor

get_prompt()

list_prompts()

download_context_file()

get_context_download_url()

Prompt

Properties

Methods

has_context()

has_system_prompt()

has_critique_prompt()

get_file_contexts()

get_url_contexts()

extract_variables()

validate_variables()

to_dict()

Dictionary-Style Access

ContextItem

Properties

Methods

is_file()

is_url()

to_dict()

Exceptions

BaytAPIError

BaytAuthError

BaytNotFoundError

BaytRateLimitError

BaytValidationError

Type Hints

Complete Example

Next Steps