Chronary Python SDK

The official Python client for the Chronary calendar-as-a-service API.

Installation

pip install chronary

Requires Python 3.10+.

Quickstart

Synchronous

from chronary import Chronary

client = Chronary(api_key="chr_sk_...")

# Create a calendar
calendar = client.calendars.create(name="Sales Team", timezone="America/New_York")

# Create an event
event = client.events.create(
    calendar.id,
    title="Strategy Sync",
    start_time="2026-03-28T14:00:00Z",
    end_time="2026-03-28T14:30:00Z",
)

# Check availability
free_slots = client.availability.get(
    "agt_abc123",
    start="2026-03-28T09:00:00Z",
    end="2026-03-28T17:00:00Z",
    slot_duration="30m",
)

Asynchronous

from chronary import AsyncChronary

async with AsyncChronary(api_key="chr_sk_...") as client:
    agent = await client.agents.create(name="Support Bot", type="ai")
    calendars = await client.agents.calendars.list(agent.id)

Configuration

Environment variable

export CHRONARY_API_KEY="chr_sk_..."

# No api_key argument needed when the env var is set
client = Chronary()

Custom options

client = Chronary(
    api_key="chr_sk_...",
    base_url="https://api.chronary.ai",  # default
    timeout=60.0,                         # seconds, default 60
    max_retries=2,                        # default 2
)

Custom httpx client

import httpx

transport = httpx.HTTPTransport(retries=3)
http_client = httpx.Client(transport=transport)

client = Chronary(api_key="chr_sk_...", httpx_client=http_client)

Resources

Agent-scoped resources

# Calendars owned by an agent
client.agents.calendars.create("agt_abc123", name="My Cal", timezone="UTC")
client.agents.calendars.list("agt_abc123")

# Events across all of an agent's calendars
client.agents.events.list("agt_abc123", start_after="2026-03-01T00:00:00Z")

# Agent availability
client.agents.availability.get("agt_abc123", start="...", end="...")

Pagination

List methods return a pager with auto_paging_iter() for transparent pagination:

pager = client.agents.list()

# Iterate through all pages automatically
for agent in pager.auto_paging_iter():
    print(agent.name)

# Or access the current page directly
print(pager.data)       # list of items
print(pager.total)      # total count
print(pager.has_more)   # whether more pages exist

Error handling

from chronary import Chronary, NotFoundError, RateLimitError, APIError

client = Chronary()

try:
    agent = client.agents.get("agt_nonexistent")
except NotFoundError:
    print("Agent not found")
except RateLimitError:
    print("Slow down")
except APIError as e:
    print(f"{e.status_code}: {e.message}")

All errors carry .status_code, .message, .request_id, .error_type, and .body.

Per-request options

Override retries on a per-call basis:

agent = client.agents.get("agt_abc123", max_retries=5)

Webhook verification

Verify incoming webhook signatures using HMAC-SHA256:

from chronary.webhook import verify_signature, SignatureVerificationError

try:
    verify_signature(
        payload=request.body,
        headers=request.headers,
        secret=webhook_secret,
    )
    # signature valid — process the event
except SignatureVerificationError:
    # reject the request (e.g. return 401)
    ...

Request IDs

Every response model carries an _request_id attribute for correlating with server logs:

agent = client.agents.get("agt_abc123")
print(agent._request_id)  # "req_..."

Plans & limits

Chronary enforces a per-key rate limit and per-org monthly quotas that vary by plan:

Pro-only feature calls raise APIError (status 403) on Free. The SDK automatically retries 429 and 5xx responses with exponential backoff (max_retries). See https://docs.chronary.ai/resources/rate-limits/ for the full matrix.

License

Apache-2.0