The Python SDK is continually evolving, with new endpoints being added for notifications, events, and more. Stay tuned for updates!

​
Overview

The Roark Python SDK provides a streamlined way to interact with the Roark API. This guide will help you quickly set up the SDK and start analyzing call recordings in your application.

​
Prerequisites

Before you begin, ensure you have:

​
Installation

Choose your preferred package manager:

pip install roark-analytics

​
Quick Start

1

Import the SDK

import os
from roark_analytics import Roark
2

Initialize the Client

client = Roark(
    bearer_token="YOUR_ROARK_API_KEY"  # Or use environment variable
)

Replace YOUR_ROARK_API_KEY with your actual API key from Roark, or use an environment variable: bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN")

3

Create an evaluation job for one or many calls

You can find the evaluator slug from the Evaluators section on the dashboard. Or you can use all to evaluate with all available evaluators.

# Create an evaluation for a single call
response = client.evaluation.create(
  # You can find the evaluator slug from the Evaluators section on the dashboard
  # Or you can use 'all' to evaluate with all available evaluators.
  #
  # Evaluators to evaluate the call
  # Usage examples:
  # - Specific evaluators: evaluators: ['evaluator-slug-1', 'evaluator-slug-2']
  # - All evaluators: evaluators: 'all'
  evaluators=['evaluator-slug-1', 'evaluator-slug-2'],
  call={
    recording_url="https://example.com/recording.wav",
    started_at="2025-03-02T05:08:35.885Z",
    call_direction="INBOUND",
    interface_type="PHONE",
    participants=[
      {"role": "AGENT", "spoke_first": True, "name": "John Doe", "phone_number": "123456789"},
      {"role": "CUSTOMER", "name": "Jane Doe", "phone_number": "123456789"},
    ],
    properties={
      # Any custom properties
      "business_name": "customer-busines-name",
      "business_id": "customer-business-id"
    },
    tool_invocations=[
      {
        "name": "book_appointment",
        "description": "Book an appointment",
        "start_offset_ms": 7000,
        "parameters": {
            # Parameters are submitted as key-value pairs
            "patient_name": "John Doe",
            "patient_phone": "+1234567890",
            "appointment_type": {
                # Parameter values can alternatively be objects which include the value and an optional description and type
                "value": "cleaning",
                "description": "Type of dental appointment",
                "type": "string",
            }
        },
        # Result can be a string or an object
        result="success",
      },
    ],
  },
)

print(response.data)
4

You're All Set

That’s it! You can now use the SDK to create evaluations

​
Additional Resources

API Reference

Explore our comprehensive API documentation

Example Repository

View example implementations and use cases

PyPI Package

View package details and stats on PyPI

GitHub Repository

Browse the source code and contribute