SuperU - AI Voice Assistant Platform

SuperU is a Python SDK for creating AI-powered voice assistants, running phone calls, and managing assistants, tools, folders, contacts, audiences, and knowledge bases from your SuperU account.

Installation

pip install superu

Quickstart

import superu

client = superu.SuperU("your_api_key")

# 1) List existing agents
agents = client.agents.list(limit=5)
print(agents)

# 2) Start an outbound call
call = client.calls.create_outbound_call(
    assistant_id="assistant_id_from_dashboard",
    to="+15557654321",
    campaign_id="demo_call",
    customer_name="Ava",
    customer_id="cust_123"
)
print(call)

Client Overview

The SDK exposes a single top-level client, SuperU, which validates your API key and provides service wrappers.

import superu

client = superu.SuperU("your_api_key")

# Wrappers available on the client
client.calls
client.agents
client.folders
client.call_logs
client.tools
client.phone_numbers
client.contacts
client.audience
client.knowledge_base

API Reference

SuperU

High-level client that validates your API key and exposes service wrappers.

Constructor

• SuperU(api_key)

Methods

• validate_api_key(api_key)

Attributes

• calls: CallWrapper
• agents: AssistantWrapper
• folders: FolderWrapper
• call_logs: CallLogsWrapper
• tools: ToolsWrapper
• phone_numbers: PhoneNumberWrapper
• contacts: ContactWrapper
• audience: AudienceWrapper
• knowledge_base: KnowledgeBaseWrapper

CallWrapper

Create and analyze calls.

Methods

• create_twilio_call(phoneNumberId, to_, assistant_id, additional_payload=None)
• analysis_twilio_call(call_uuid, custom_fields=None)
• create_outbound_call(assistant_id, to, from_=None, campaign_id='demo_call', customer_name='Unknown', customer_id='Unknown', variable_values=None)

Custom analysis fields format

• Each item must be a dict with keys: field, definition, outputs_options.
• field and definition must be strings.
• outputs_options must be a list of strings.

Example

twilio_call = client.calls.create_twilio_call(
    phoneNumberId="pn_123",
    to_="+15557654321",
    assistant_id="assistant_id_from_dashboard"
)
print(twilio_call)

analysis = client.calls.analysis_twilio_call(
    call_uuid="call_uuid_here",
    custom_fields=[
        {
            "field": "intent",
            "definition": "Primary intent of the caller",
            "outputs_options": ["sales", "support", "other"]
        }
    ]
)
print(analysis)

AssistantWrapper

Manage agents and agent versions.

Methods

• create_version(agent_id, version, assistant_data, knowledge_base=None, tools=None, call_forwarding=None)
• update_version(agent_id, version_id, version=None, assistant_data=None, composio_app=None)
• list(page=1, limit=20, inbound_or_outbound=None, search_query=None)
• get_version(agent_id, version)
• list_versions(agent_id)
• deploy_version(agent_id, version_id)
• create_agent(type=None, name=None, company_name=None, assistant_name=None, first_message=None, voice_id=None, voice_provider='11labs', speed='1.0', bg_noice=False, system_prompt=None, industry='Blank Template', useCase='Blank Template', form_model=None, assistant_data=None, knowledge_base=None, tools=None, call_forwarding=None)
• update_name(agent_id, name)
• import_agents()
• delete(agent_id)

Example

agent = client.agents.create_agent(
    type="outbound",
    name="Demo Assistant",
    assistant_name="Demo Voice",
    first_message="Hello! This is a demo call.",
    system_prompt="You are a friendly assistant.",
    voice_id="90ipbRoKi4CpHXvKVtl0"
)
print(agent)

PhoneNumberWrapper

Retrieve owned phone numbers.

Methods

• get_owned()

Example

numbers = client.phone_numbers.get_owned()
print(numbers)

CallLogsWrapper

Retrieve call logs with filtering.

Methods

• get_logs(assistant_id='all', limit=20, page=1, before=None, after=None, status=None, campaign_id=None, search_query=None)

Example

logs = client.call_logs.get_logs(assistant_id="all", limit=10, page=1)
print(logs)

ToolsWrapper

Create and manage tools your agents can call.

Methods

• create(tool_data)
• list(page=1, per_page=20, tool_type=None)
• get(tool_id)
• update(tool_id, update_data)
• delete(tool_id)

Example

tool = client.tools.create({
    "name": "check-user-status",
    "description": "Check if a user exists in our database",
    "parameters": {
        "type": "object",
        "properties": {
            "email": {"type": "string", "description": "User email"}
        },
        "required": ["email"]
    },
    "tool_url": "/api/check-user",
    "tool_url_domain": "https://your-api.com",
    "async_": False
})
print(tool)

FolderWrapper

Organize agents into folders.

Methods

• create(folder_name, description=None)
• list(page=1, per_page=20)
• get(folder_id)
• update(folder_id, folder_name=None, description=None)
• delete(folder_id)
• assign_agent(agent_id, folder_id=None)
• get_agents(folder_id, page=1, per_page=20)

Example

folder = client.folders.create("Outbound Agents", description="Sales and support")
folder_id = folder.get("folder_id")

if folder_id:
    client.folders.assign_agent(agent_id="assistant_id_from_dashboard", folder_id=folder_id)
    print(client.folders.get_agents(folder_id))

ContactWrapper

Create and list contacts with validation.

Methods

• create(first_name, last_name, email, country_code, phone_number, audience_id=None)
• list(page=1, limit=10, search_query=None)

Validation

• Email, phone number, and country code are validated before sending the request.

Example

contact = client.contacts.create(
    first_name="Ava",
    last_name="Patel",
    email="ava.patel@example.com",
    country_code="+1",
    phone_number="5551234567"
)
print(contact)

AudienceWrapper

Create, update, and manage audiences and their contacts.

Methods

• create(audience_name, contacts, audience_description='')
• list()
• get(audience_id)
• get_contacts(audience_id, page=1, limit=10)
• update(audience_id, audience_name=None, audience_description=None)
• add_contacts(audience_id, contacts)
• delete(audience_id)

Contact format

• Required: first_name, country_code, phone_number
• Optional: last_name, email, variable_values

Example

audience = client.audience.create(
    audience_name="Demo Audience",
    contacts=[
        {
            "first_name": "Ava",
            "country_code": "+1",
            "phone_number": "5551234567"
        }
    ]
)
print(audience)

KnowledgeBaseWrapper

Create and manage knowledge bases with file uploads.

Methods

• create(name, description, files)
• list(page=1, limit=10)
• get(knowledge_base_id)

Files format

• File-like objects: open("file.pdf", "rb")
• Tuples: (filename, content, content_type)

Example

with open("faq.pdf", "rb") as f:
    kb = client.knowledge_base.create(
        name="FAQ",
        description="Frequently asked questions",
        files=[f]
    )
print(kb)

Error Handling

Methods validate inputs and raise ValueError for invalid data. API failures raise Exception when non-success status codes are returned.

Support

• Documentation: https://docs.superu.ai
• Issues: https://github.com/superu/superu-python/issues
• Email: Contact support via your SuperU dashboard

License

This project is licensed under the MIT License. See LICENSE.