### Quick start: list agents and create outbound call

Source: https://docs.superu.ai/api-reference/introduction

Quick start example showing how to initialize the SuperU client, list existing agents, and start an outbound call. Replace 'your_api_key' with your actual key and provide valid assistant_id and phone number.

```python
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)
```

--------------------------------

### Python SDK example to get a tool

Source: https://docs.superu.ai/api-reference/tools/get-tool

Uses the SuperU Python SDK to fetch a tool by its ID. Initialize the client with your API key and call the get tool method with the tool_id.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

tool_id = "0a425650-60ac-4fd4-9554-5579844ce3e5"
```

--------------------------------

### Get Agent Version Response Example

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Example response body returned upon a successful 200 status, containing the agent configuration, knowledge base, and tools.

```json
{
  "version_id": "69c228b11e62cb42009fe445",
  "agent_id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
  "version": "1.0.1",
  "assistant_config": {
    "id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
    "orgId": "1d23cc8c-8ccb-4a19-a1e8-d2dc72e8848d",
    "name": "Acme Dental Clinic - AI Receptionist",
    "voice": {
      "model": "eleven_turbo_v2_5",
      "voiceId": "EXAVITQu4vr4xnSDxMaL",
      "provider": "11labs"
    },
    "model": {
      "model": "openai/gpt-oss-120b",
      "provider": "groq",
      "messages": [
        {
          "role": "system",
          "content": "You are Emma, the warm and professional AI\nreceptionist for Acme Dental Clinic..."
        }
      ]
    },
    "firstMessage": "Thank you for calling Acme Dental Clinic! This is Emma. How\ncan I help you today?",
    "transcriber": {
      "model": "nova-2",
      "language": "en",
      "provider": "deepgram"
    },
    "analysisPlan": {
      "summaryPlan": {
        "messages": [
          {
            "role": "system",
            "content": "Create a concise call summary and structured\ndetails..."
          }
        ]
      }
    },
    "messagePlan": {
      "idleMessages": [
        "Are you there?",
        "Can you hear me?",
        "Should I continue?"
      ],
      "idleMessageMaxSpokenCount": 2,
      "idleTimeoutSeconds": 5
    },
    "server": {
      "url": "https://voip-middlware.superu.ai/vapi/webhook",
      "timeoutSeconds": 20
    }
  },
  "knowledge_base": {},
  "tools": [],
  "composio_app": {},
  "call_forwarding": null,
  "created_at": "2026-03-24 06:01:21"
}
```

--------------------------------

### Get Agent Version Python Client Initialization

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Example of initializing the SuperU Python client.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")
```

--------------------------------

### Python client setup for creating a folder

Source: https://docs.superu.ai/api-reference/folders/create-folder

Python example using the SuperU client to create a folder. It initializes the client with your API key and prepares a payload with folder_name and description. The example stops at payload construction; the actual API call is not shown.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "folder_name": "Outbound Agents",
    "description": "Sales and support"
}

```

--------------------------------

### Python client example for getting a folder

Source: https://docs.superu.ai/api-reference/folders/get-folder

Uses the client's folders.get method with a folder_id to retrieve folder details and prints the response.

```python
response = client.folders.get(folder_id)
print(response)
```

--------------------------------

### Install SuperU SDK with pip

Source: https://docs.superu.ai/api-reference/introduction

Install the SuperU Python SDK using pip.

```bash
pip install superu
```

--------------------------------

### Get Agent Version Request Example

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Example request body for the Get agent version endpoint, requiring the agent_id and version identifier.

```json
{
  "agent_id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
  "version": "1.0.0"
}
```

--------------------------------

### NotFound Response Example

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example of a 404 Not Found response.

```json
{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "Resource not found."
}
```

--------------------------------

### Install SuperU community node package

Source: https://docs.superu.ai/api-reference/n8n-installation

Copy this package name to install the SuperU community node in n8n via Settings > Community Nodes > Install.

```bash
@superuai/n8n-nodes-superu
```

--------------------------------

### Create Agent Version Request Example

Source: https://docs.superu.ai/api-reference/agent-versions/create-agent-version

Example of creating an agent version using the client.agents.create_version method with a payload containing agent_id, version, and assistant_data.

```python
response = client.agents.create_version(**payload)
print(response)
```

--------------------------------

### Get audience with cURL and Python

Source: https://docs.superu.ai/api-reference/audiences/get-audience

Retrieves detailed audience data for a specific audience ID. The cURL example sends a GET request to the /audience/{audience_id} endpoint with the superU-Api-Key header. The Python example initializes the SuperU client with your API key and sets the audience_id variable to the example ID.

```curl
curl --request GET \
  --url https://voip-middlware.superu.ai/audience/597b3dde-9169-4017-800d-f97a5fabebe3 \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

audience_id = "597b3dde-9169-4017-800d-f97a5fabebe3"
```

--------------------------------

### List audiences with cURL and Python

Source: https://docs.superu.ai/api-reference/audiences/list-audiences

Use the cURL command to call the GET /audience/list endpoint with the superU-Api-Key header and optional page and limit query parameters. The Python example initializes the SuperU client with your API key and prepares a payload with page and limit values. Both examples target the same endpoint and require a valid SuperU API key.

```curl
curl --request GET \
  --url https://voip-middlware.superu.ai/audience/list?page=1&limit=10 \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "page": "1",
    "limit": "10"
}
```

--------------------------------

### List knowledge bases Python client

Source: https://docs.superu.ai/api-reference/knowledge-base/list-knowledge-bases

Example Python code to list knowledge bases using the SuperU SDK.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "page": 1,
    "limit": 10
}
```

--------------------------------

### Create Audience OpenAPI Request Example

Source: https://docs.superu.ai/api-reference/audiences/create-audience

Example JSON request body for creating an audience with initial contact details.

```json
{
  "audience_name": "Demo Audience",
  "contacts": [
    {
      "first_name": "Ava",
      "last_name": "Patel",
      "email": "ava.patel@example.com",
      "country_code": "+1",
      "phone_number": "5551234567",
      "variable_values": {
        "key": "value"
      }
    }
  ],
  "audience_description": "Leads from webinar"
}
```

--------------------------------

### Get Agent Version cURL Request

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Example of how to call the endpoint using cURL. Replace YOUR_SUPERU_API_KEY with your actual API key.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/agent/version/get \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "agent_id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
  "version": "69f884d50c4e5a2dc72277d4"
}'
```

--------------------------------

### NotImplemented Response Example

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example of a 501 Not Implemented response.

```json
{
  "status": "error",
  "code": "NOT_IMPLEMENTED",
  "message": "This endpoint is not implemented for your workspace."
}
```

--------------------------------

### Create Audience OpenAPI Response Example

Source: https://docs.superu.ai/api-reference/audiences/create-audience

Example JSON response returned upon successful creation of an audience.

```json
{
  "message": "Audience created successfully",
  "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3",
  "audience_name": "Demo Audience",
  "audience_description": "Leads from webinar",
  "total_contacts": 1,
  "contacts_added": 1,
  "contacts": [
    {
      "id": "69f9a9a1c2647606b8c43154",
      "first_name": "Ava",
      "last_name": "Patel",
      "email": "ava.patel@example.com",
      "country_code": "+1",
      "phone_number": "5551234567"
    }
  ]
}
```

--------------------------------

### OpenAPI: Error Response Examples

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Example error responses for BadRequest, Unauthorized, NotFound, InternalServerError, and NotImplemented scenarios.

```yaml
BadRequest:
  description: Bad Request - invalid parameters or payload.
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
      example:
        status: error
        code: BAD_REQUEST
        message: Request validation failed.
```

```yaml
Unauthorized:
  description: Unauthorized - missing or invalid API key.
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
      example:
        status: error
        code: UNAUTHORIZED
        message: Invalid or missing superU-Api-Key.
```

```yaml
NotFound:
  description: Not Found - requested resource does not exist.
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
      example:
        status: error
        code: NOT_FOUND
        message: Resource not found.
```

```yaml
InternalServerError:
  description: Internal Server Error - unexpected backend error.
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
      example:
        status: error
        code: INTERNAL_SERVER_ERROR
        message: An unexpected server error occurred.
```

```yaml
NotImplemented:
  description: >-
    Not Implemented - this action is not available in the current
    deployment.
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
      example:
        status: error
        code: NOT_IMPLEMENTED
        message: This endpoint is not implemented for your workspace.
```

--------------------------------

### Create Knowledge Base via cURL

Source: https://docs.superu.ai/api-reference/knowledge-base/create-knowledge-base

Example request to create a knowledge base using cURL. Replace YOUR_SUPERU_API_KEY with your actual API key.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/knowledge-base/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --form 'name=FAQ' \
  --form 'description=Frequently asked questions' \
  --form 'files=@/path/to/file.pdf'
```

--------------------------------

### Create Agent cURL Request

Source: https://docs.superu.ai/api-reference/agents/create-agent

Example of how to create an agent using a cURL command with the required API key header.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/agent/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "type": "outbound",
  "name": "Demo Assistant",
  "company_name": "SuperU",
  "assistant_name": "Ava",
  "first_message": "Hi, thanks for taking the call.",
  "voice_id": "90ipbRoKi4CpHXvKVtl0",
  "voice_provider": "11labs",
  "system_prompt": "You are a friendly assistant.",
  "industry": "Blank Template",
  "useCase": "Blank Template",
  "form_model": {
    "key": "value"
  },
  "assistant_data": {
    "key": "value"
  },
  "knowledgeBase": [
    "kb_abc123"
  ],
  "tools": [
    "tool_01HXR9259WDZ2X3ZZKQ7HDG4C2"
  ],
  "call_forwarding": {
    "key": "value"
  }
}'
```

--------------------------------

### BadRequest Response Example

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example of a 400 Bad Request response.

```json
{
  "status": "error",
  "code": "BAD_REQUEST",
  "message": "Request validation failed."
}
```

--------------------------------

### Create Contact Python Client Call

Source: https://docs.superu.ai/api-reference/contacts/create-contact

Example of invoking the contact creation method using the client library.

```python
response = client.contacts.create(**payload)
print(response)
```

--------------------------------

### Python client example for create outbound call

Source: https://docs.superu.ai/api-reference/calls/create-outbound-call

Uses the SuperU Python client to create an outbound call. Requires the superu package and a valid API key.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

response = client.calls.create_outbound_call(
    assistant_id="ag_01HXR8FM5QYCVXAK4TYFJ4AEP0",
    to="+14155552671",
    from="+14155550000",
    campaign_id="demo_call",
    customer_name="Ava",
    customer_id="cust_123",
    variable_values={"key": "value"}
)

print(response)
```

--------------------------------

### List knowledge bases cURL request

Source: https://docs.superu.ai/api-reference/knowledge-base/list-knowledge-bases

Example cURL command to list knowledge bases using the SuperU API.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/knowledge-base/list \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "page": 1,
  "limit": 10
}'
```

--------------------------------

### Webhook Payload Example

Source: https://docs.superu.ai/api-reference/webhooks/call-ended

An example of the JSON payload sent by SuperU to your webhook endpoint.

```json
{
  "call_uuid": "c1a2b3d4-e5f6-7890-abcd-ef1234567890"
}
```

--------------------------------

### InternalServerError Response Example

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example of a 500 Internal Server Error response.

```json
{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected server error occurred."
}
```

--------------------------------

### Update folder Python client

Source: https://docs.superu.ai/api-reference/folders/update-folder

Example Python code to update a folder using the SuperU SDK.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "folder_id": "25388237-72ba-46a9-b8b5-f0341939775c",
    "folder_name": "Outbound Team",
    "description": "Top of funnel campaigns"
}
```

--------------------------------

### Unauthorized Response Example

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example of a 401 Unauthorized response due to missing or invalid API key.

```json
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing superU-Api-Key."
}
```

--------------------------------

### Retrieve call logs with filters (cURL and Python)

Source: https://docs.superu.ai/api-reference/call-logs/get-call-logs-and-analysis

Use the POST /call-logs/all endpoint to retrieve call logs with filtering by date range, status, campaign, and search query. The cURL example sends a request with the superU-Api-Key header; the Python example initializes the SuperU client with your API key.

```curl
curl --request POST \
  --url https://voip-middlware.superu.ai/call-logs/all?limit=20&page=1&before=2026-02-01T00%3A00%3A00Z&after=2026-01-01T00%3A00%3A00Z&status=completed&campaign_id=demo_call&search_query=Ava \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")
```

--------------------------------

### Python: Get Agent Version with client.agents.get_version

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Shows how to call the get_version endpoint with an agent_id and version payload, then print the response.

```python
payload = {
    "agent_id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
    "version": "69f884d50c4e5a2dc72277d4"
}

response = client.agents.get_version(**payload)
print(response)
```

--------------------------------

### Create Audience cURL Request

Source: https://docs.superu.ai/api-reference/audiences/create-audience

Example cURL command to create an audience. Replace YOUR_SUPERU_API_KEY with your actual API key.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/audience/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "audience_name": "Demo Audience",
  "audience_description": "Leads from webinar",
  "contacts": [
    {
      "first_name": "Ava",
      "last_name": "Patel",
      "email": "ava.patel@example.com",
      "country_code": "+1",
      "phone_number": "5551234567",
      "variable_values": {
        "key": "value"
      }
    }
  ]
}'
```

--------------------------------

### Python client request for List contacts

Source: https://docs.superu.ai/api-reference/contacts/list-contacts

Example Python code using the SuperU SDK to list contacts with pagination and search parameters.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "page": "1",
    "limit": "10",
    "search_query": "ava"
}
```

--------------------------------

### Python request to get knowledge base

Source: https://docs.superu.ai/api-reference/knowledge-base/get-knowledge-base

Uses the SuperU Python client to fetch knowledge base details. Requires the superu package and a valid API key.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

knowledge_base_id = "a7aba494-c043-455c-8429-3ae7e58f957e"
```

--------------------------------

### Python request to get folder

Source: https://docs.superu.ai/api-reference/folders/get-folder

Uses the SuperU Python client to retrieve folder details. Requires the superu package and an API key.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

folder_id = "a3740204-726f-4547-b0f8-8831a5147207"
```

--------------------------------

### Create Knowledge Base with Python Client

Source: https://docs.superu.ai/api-reference/knowledge-base/create-knowledge-base

Initializes the SuperU client with an API key and uploads a file to create a new knowledge base.

```python
client = SuperU("YOUR_SUPERU_API_KEY")
with open("sample.pdf", "rb") as f:
    response = client.knowledge_base.create(
        name="FAQ",
        description="Frequently asked questions",
        files=[f]
    )
print(response)
```

--------------------------------

### cURL request to get a tool

Source: https://docs.superu.ai/api-reference/tools/get-tool

Sends a POST request to the /tool/{tool_id} endpoint with the SuperU API key header. Replace YOUR_SUPERU_API_KEY with your actual API key.

```curl
curl --request POST \
  --url https://voip-middlware.superu.ai/tool/0a425650-60ac-4fd4-9554-5579844ce3e5 \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

--------------------------------

### Get Call Status Request

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example usage of the get_call_status method to retrieve the status of a call by its UUID.

```python
response = client.calls.get_call_status(
    call_uuid="e8f87167-d4fd-44f2-b03a-24cb600f86f2"
)
print(response)
```

--------------------------------

### OpenAPI: AgentVersionGetRequest Schema

Source: https://docs.superu.ai/api-reference/agent-versions/get-agent-version

Defines the request schema for getting an agent version, requiring agent_id and version fields with example values.

```yaml
AgentVersionGetRequest:
  allOf:
    - type: object
      required:
        - agent_id
        - version
      properties:
        agent_id:
          type: string
          description: Agent ID
          example: 04cf74f7-019b-4c3d-883c-610a42b32bc4
        version:
          type: string
          description: Version ID
          example: 69f884d50c4e5a2dc72277d4
  description: Agent Version Get Request schema.
```

--------------------------------

### List audience contacts with cURL and Python

Source: https://docs.superu.ai/api-reference/audiences/list-audience-contacts

Use the cURL command to call the GET /audience/contacts/list endpoint with the required audience_id query parameter and optional page and limit parameters. The Python snippet shows how to initialize the SuperU client with your API key and construct the payload for the same request. Both examples use the example audience ID 597b3dde-9169-4017-800d-f97a5fabebe3.

```curl
curl --request GET \
  --url https://voip-middlware.superu.ai/audience/contacts/list?audience_id=597b3dde-9169-4017-800d-f97a5fabebe3&page=1&limit=10 \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3",
    "page": 1,
    "limit": 10
}
```

--------------------------------

### Create tool with Python SDK

Source: https://docs.superu.ai/api-reference/tools/create-tool

Initializes the SuperU client for interacting with the API using Python.

```python
from superu import SuperU
```

--------------------------------

### OpenAPI specification for Get tool

Source: https://docs.superu.ai/api-reference/tools/get-tool

The OpenAPI 3.1.0 specification for the POST /tool/{tool_id} endpoint. It defines the request parameters, response schemas, and error responses. The tool_id is a required path parameter with a default example value.

```yaml
openapi: 3.1.0
info:
  title: SuperU API
  description: >-
    Comprehensive API reference for SuperU voice agents, calls, tools, contacts,
    audiences, and knowledge bases.
  version: 1.0.0
servers:
  - url: https://voip-middlware.superu.ai
    description: Production
security:
  - superUApiKey: []
tags:
  - name: Calls
    description: Create and analyze calls.
  - name: Agents
    description: Create, list, import, update, and delete agents.
  - name: Agent Versions
    description: Manage versions for existing agents.
  - name: Phone Numbers
    description: Fetch phone numbers available in your account.
  - name: Call Logs
    description: Retrieve call history with filters.
  - name: Tools
    description: Create and manage callable tools.
  - name: Folders
    description: Organize agents into folders.
  - name: Contacts
    description: Create and list contacts.
  - name: Audiences
    description: Create and manage audiences and contacts.
  - name: Knowledge Base
    description: Upload and manage knowledge bases.
  - name: Campaigns
    description: Create and manage outbound campaigns with automated workflows.
paths:
  /tool/{tool_id}:
    post:
      tags:
        - Tools
      summary: Get tool
      description: Fetches one tool by ID.
      operationId: getTool
      parameters:
        - name: tool_id
          in: path
          description: Tool ID
          required: true
          schema:
            type: string
            default: 0a425650-60ac-4fd4-9554-5579844ce3e5
            example: 0a425650-60ac-4fd4-9554-5579844ce3e5
      responses:
        '200':
          description: Tool details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                _id: 69f98c2185578cdac8d33014
                tool_uuid: 0a425650-60ac-4fd4-9554-5579844ce3e7
                user_id: user_32UrXxvrVxWSYp1dGLsPdElDtRu
                type: apiRequest
                createdAt: '2026-05-05T06:20:17.548000'
                updatedAt: '2026-05-05T06:20:17.548000'
                method: GET
                url: https://www.google.com
                name: New Tool
                description: new
                timeoutSeconds: 20
                body: {}
                headers: {}
                messages: []
                backoffPlan:
                  type: fixed
                  maxRetries: 0
                  baseDelaySeconds: 1
                  excludedStatusCodes:
                    - 400
                    - 401
                    - 403
                    - 404
                variableExtractionPlan: null
                rejectionPlan: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
```

--------------------------------

### Python: Create Outbound Call

Source: https://docs.superu.ai/api-reference/calls/create-outbound-call

Example of creating an outbound call with the SuperU AI client. Requires assistant_id, to, and from; optional fields include campaign_id, customer_name, customer_id, and variable_values.

```python
response = client.calls.create_outbound_call(
    assistant_id="ag_01HXR8FM5QYCVXAK4TYFJ4AEP0",
    to="+14155552671",
    from_="+14155550000",
    campaign_id="demo_call",
    customer_name="Ava",
    customer_id="cust_123",
    variable_values={
        "key": "value"
    }
)
print(response)
```

--------------------------------

### POST /folder/create

Source: https://docs.superu.ai/api-reference/folders/create-folder

Creates a new folder to organize agents. This endpoint accepts a folder name and optional description, and returns the created folder details.

```APIDOC
## POST /folder/create

### Description
Creates a new folder to organize agents.

### Method
POST

### Endpoint
https://voip-middlware.superu.ai/folder/create

### Parameters
#### Request Body
- **folder_name** (string) - Required - The name of the folder to create.
- **description** (string) - Optional - A description for the folder.

### Request Example
{
  "folder_name": "Outbound Agents",
  "description": "Sales and support"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **folder** (object) - The created folder object.
  - **folder_id** (string) - Unique identifier for the folder.
  - **user_id** (string) - Identifier of the user who owns the folder.
  - **name** (string) - The folder name.
  - **description** (string) - The folder description.
  - **agent_ids** (array) - List of agent IDs in the folder.
  - **created_at** (string) - Timestamp when the folder was created.
  - **updated_at** (string) - Timestamp when the folder was last updated.
  - **_id** (string) - Internal identifier for the folder.

#### Response Example
{
  "success": true,
  "folder": {
    "folder_id": "25388237-72ba-46a9-b8b5-f0341939775c",
    "user_id": "user_32UrXxvrVxWSYp1dGLsPdElDtRu",
    "name": "Outbound Agents",
    "description": "Sales and support",
    "agent_ids": [],
    "created_at": "2026-05-05T08:03:05.855Z",
    "updated_at": "2026-05-05T08:03:05.855Z",
    "_id": "69f9a4393fd42c4dfc2aaaa9"
  }
}

### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **404** - Not Found
- **500** - Internal Server Error
- **501** - Not Implemented

### Authentication
Requires an API key. Include the header `superU-Api-Key: YOUR_SUPERU_API_KEY`.

### Code Samples
#### cURL
```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/folder/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "folder_name": "Outbound Agents",
  "description": "Sales and support"
}'
```

#### Python
```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "folder_name": "Outbound Agents",
    "description": "Sales and support"
}
```
```

--------------------------------

### POST /knowledge-base/create

Source: https://docs.superu.ai/api-reference/knowledge-base/create-knowledge-base

Creates a knowledge base and uploads CSV/PDF files. This endpoint accepts multipart/form-data with the knowledge base name, description, and files to upload.

```APIDOC
## POST /knowledge-base/create

### Description
Creates a knowledge base and uploads CSV/PDF files.

### Method
POST

### Endpoint
https://voip-middlware.superu.ai/knowledge-base/create

### Parameters
#### Request Body (multipart/form-data)
- **name** (string) - Required - Knowledge base name
- **description** (string) - Required - Knowledge base description
- **files** (array of binary) - Required - Files to upload

### Request Example
```
curl --request POST \
  --url https://voip-middlware.superu.ai/knowledge-base/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --form 'name=FAQ' \
  --form 'description=Frequently asked questions' \
  --form 'files=@/path/to/file.pdf'
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response
- **message** (string) - Success message
- **data** (object) - Contains knowledge base details
  - **knowledge_base_id** (string) - ID of the created knowledge base
  - **kb_uuid** (string) - UUID of the knowledge base
  - **name** (string) - Knowledge base name
  - **description** (string) - Knowledge base description
  - **total_files** (integer) - Number of uploaded files
  - **files** (array) - List of uploaded files
    - **original_filename** (string) - Original file name
    - **s3_key** (string) - S3 key of the file
    - **file_url** (string) - URL of the file
    - **file_size** (integer) - File size in bytes
    - **uploaded_at** (string) - Upload timestamp
  - **embedding_status** (string) - Status of embedding processing
  - **created_at** (string) - Creation timestamp

#### Response Example
```json
{
  "status": "success",
  "message": "Knowledge base created successfully. Knowledge base created with embeddings. Processed 1 files into 39 chunks.",
  "data": {
    "knowledge_base_id": "69f9ac509e0388ee380f73d1",
    "kb_uuid": "a7aba494-c043-455c-8429-3ae7e58f957e",
    "name": "FAQ",
    "description": "Frequently asked questions",
    "total_files": 1,
    "files": [
      {
        "original_filename": "faq.pdf",
        "s3_key": "knowledge-base/686e8db4-15df-435e-84fe-b5f6334c2015-faq.pdf",
        "file_url": "https://pluto-superu.s3.amazonaws.com/knowledge-base/686e8db4-15df-435e-84fe-b5f6334c2015-5_letters.csv",
        "file_size": 27500,
        "uploaded_at": "2026-05-05T08:37:36.632Z"
      }
    ],
    "embedding_status": "completed",
    "created_at": "2026-05-05T08:37:36.632484"
  }
}
```

### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **404** - Not Found
- **500** - Internal Server Error
- **501** - Not Implemented
```

--------------------------------

### List tools with cURL and Python

Source: https://docs.superu.ai/api-reference/tools/list-tools

Use these examples to call the POST /tool/list endpoint. The cURL command sends a request with the superU-Api-Key header and a JSON body containing page, per_page, and type. The Python snippet initializes the SuperU client with your API key and builds the same payload.

```curl
curl --request POST \
  --url https://voip-middlware.superu.ai/tool/list \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "page": 1,
  "per_page": 20,
  "type": "apiRequest"
}'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "page": 1,
    "per_page": 20,
    "type": "apiRequest"
}
```

--------------------------------

### Create contact with Python

Source: https://docs.superu.ai/api-reference/contacts/create-contact

Use this Python snippet to create a contact using the SuperU client. Initialize the client with your API key and pass the contact payload.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "first_name": "Ava",
    "last_name": "Patel",
    "email": "ava.patel@example.com",
    "country_code": "+1",
    "phone_number": "5551234567",
    "audience_id": "a3740204-726f-4547-b0f8-8831a5147208"
}
```

--------------------------------

### API Error Response Examples

Source: https://docs.superu.ai/api-reference/contacts/create-contact

Examples of various error responses returned by the API.

```yaml
status: error
code: BAD_REQUEST
message: Request validation failed.
```

```yaml
status: error
code: UNAUTHORIZED
message: Invalid or missing superU-Api-Key.
```

```yaml
status: error
code: NOT_FOUND
message: Resource not found.
```

```yaml
status: error
code: INTERNAL_SERVER_ERROR
message: An unexpected server error occurred.
```

```yaml
status: error
code: NOT_IMPLEMENTED
message: This endpoint is not implemented for your workspace.
```

--------------------------------

### Deploy agent version with Python SDK

Source: https://docs.superu.ai/api-reference/agent-versions/deploy-agent-version

Uses the SuperU Python SDK to deploy an agent version. Initializes the client with an API key, sets the payload with agent_id and version, and deploys by sending the payload.

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "agent_id": "04cf74f7-019b-4c3d-883c-610a42b32bc4",
    "version": "1.0.0"
}
```

--------------------------------

### Create Tool Python Client Call

Source: https://docs.superu.ai/api-reference/tools/create-tool

Use the client.tools.create method to initiate a tool creation request.

```python
response = client.tools.create(**payload)
print(response)
```

--------------------------------

### Update audience with cURL and Python

Source: https://docs.superu.ai/api-reference/audiences/update-audience

Use these examples to update an audience's name and/or description via the PUT /audience/update endpoint. The cURL example sends the request with the superU-Api-Key header and a JSON body containing audience_id, audience_name, and audience_description. The Python example uses the SuperU client to construct the same payload; both require YOUR_SUPERU_API_KEY.

```curl
curl --request PUT \
  --url https://voip-middlware.superu.ai/audience/update \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3",
  "audience_name": "Demo Audience - Q1",
  "audience_description": "Qualified leads"
}'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3",
    "audience_name": "Demo Audience - Q1",
    "audience_description": "Qualified leads"
}
```

--------------------------------

### POST /agent/create

Source: https://docs.superu.ai/api-reference/agents/create-agent

Creates a new SuperU voice agent.

```APIDOC
## POST /agent/create

### Description
Creates a new SuperU voice agent.

### Method
POST

### Endpoint
https://voip-middlware.superu.ai/agent/create

### Parameters
#### Request Body
- **type** (string) - Optional - Type of agent (e.g., outbound)
- **name** (string) - Optional - Name of the agent
- **company_name** (string) - Optional - Company name
- **assistant_name** (string) - Optional - Assistant name
- **first_message** (string) - Optional - Initial message
- **voice_id** (string) - Optional - Voice identifier
- **voice_provider** (string) - Optional - Voice provider (e.g., 11labs)
- **system_prompt** (string) - Optional - System prompt
- **industry** (string) - Optional - Industry template
- **useCase** (string) - Optional - Use case template
- **form_model** (object) - Optional - Form model data
- **assistant_data** (object) - Optional - Assistant data
- **knowledgeBase** (array) - Optional - List of knowledge base IDs
- **tools** (array) - Optional - List of tool IDs
- **call_forwarding** (object) - Optional - Call forwarding configuration

### Request Example
```json
{
  "type": "outbound",
  "name": "Demo Assistant",
  "company_name": "SuperU",
  "assistant_name": "Ava",
  "first_message": "Hi, thanks for taking the call.",
  "voice_id": "90ipbRoKi4CpHXvKVtl0",
  "voice_provider": "11labs",
  "system_prompt": "You are a friendly assistant.",
  "industry": "Blank Template",
  "useCase": "Blank Template",
  "form_model": {
    "key": "value"
  },
  "assistant_data": {
    "key": "value"
  },
  "knowledgeBase": [
    "kb_abc123"
  ],
  "tools": [
    "tool_01HXR9259WDZ2X3ZZKQ7HDG4C2"
  ],
  "call_forwarding": {
    "key": "value"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response
- **agent_id** (string) - ID of the created agent
- **message** (string) - Success message

#### Response Example
```json
{
  "status": "success",
  "agent_id": "ag_01HXR8FM5QYCVXAK4TYFJ4AEP0",
  "message": "Agent created successfully"
}
```

### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **404** - Not Found
- **500** - Internal Server Error
- **501** - Not Implemented

### Authentication
Requires a SuperU API key. Include the header `superU-Api-Key: YOUR_SUPERU_API_KEY`.

### cURL Example
```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/agent/create \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "type": "outbound",
  "name": "Demo Assistant",
  "company_name": "SuperU",
  "assistant_name": "Ava",
  "first_message": "Hi, thanks for taking the call.",
  "voice_id": "90ipbRoKi4CpHXvKVtl0",
  "voice_provider": "11labs",
  "system_prompt": "You are a friendly assistant.",
  "industry": "Blank Template",
  "useCase": "Blank Template",
  "form_model": {
    "key": "value"
  },
  "assistant_data": {
    "key": "value"
  },
  "knowledgeBase": [
    "kb_abc123"
  ],
  "tools": [
    "tool_01HXR9259WDZ2X3ZZKQ7HDG4C2"
  ],
  "call_forwarding": {
    "key": "value"
  }
}'
```

--------------------------------

### cURL request to get knowledge base

Source: https://docs.superu.ai/api-reference/knowledge-base/get-knowledge-base

Sends a GET request to the SuperU API to retrieve details for a knowledge base. Requires the knowledge_base_id in the URL and a valid API key in the superU-Api-Key header.

```curl
curl --request GET \
  --url https://voip-middlware.superu.ai/knowledge-base/a7aba494-c043-455c-8429-3ae7e58f957e \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

--------------------------------

### Delete audience with cURL and Python

Source: https://docs.superu.ai/api-reference/audiences/delete-audience

Delete an audience by its ID. The cURL example sends a DELETE request to /audience/delete with the audience_id in the JSON body. The Python example initializes the SuperU client with your API key and prepares the same payload.

```curl
curl --request DELETE \
  --url https://voip-middlware.superu.ai/audience/delete \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3"
}'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "audience_id": "597b3dde-9169-4017-800d-f97a5fabebe3"
}
```

--------------------------------

### Update agent name with cURL and Python

Source: https://docs.superu.ai/api-reference/agents/update-agent-name

Updates the display name of an existing agent using the POST /agent/update/name endpoint. The request body requires agent_id and name. The cURL example uses the superU-Api-Key header; the Python example uses the SuperU client with YOUR_SUPERU_API_KEY.

```curl
curl --request POST \
  --url https://voip-middlware.superu.ai/agent/update/name \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "agent_id": "76286489-86a8-4540-b479-b0154e474555",
  "name": "Testinggg"
}'
```

```python
from superu import SuperU

client = SuperU("YOUR_SUPERU_API_KEY")

payload = {
    "agent_id": "76286489-86a8-4540-b479-b0154e474555",
    "name": "Testinggg"
}
```

--------------------------------

### Update folder using Python client

Source: https://docs.superu.ai/api-reference/folders/update-folder

Python example showing how to call the update folder endpoint using the client library. The payload should contain the folder_id and the fields to update.

```python
response = client.folders.update(**payload)
print(response)
```

--------------------------------

### cURL request for call status

Source: https://docs.superu.ai/api-reference/calls/get-call-status

Example command to fetch call status using cURL.

```bash
curl --request GET \
  --url 'https://voip-middlware.superu.ai/call-status?call_uuid=e8f87167-d4fd-44f2-b03a-24cb600f86f2' \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```

--------------------------------

### Create tool via cURL

Source: https://docs.superu.ai/api-reference/tools/create-tool

Use this cURL command to create a new tool by sending a POST request to the /tool endpoint. Ensure you replace YOUR_SUPERU_API_KEY with your actual API key.

```bash
curl --request POST \
  --url https://voip-middlware.superu.ai/tool \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY' \
  --data '{
  "name": "Tool 1",
  "type": "apiRequest",
  "url": "https://www.google.com",
  "description": "hehe",
  "method": "GET",
  "body": {
    "type": "object",
    "properties": {
      "new": {
        "type": "string",
        "description": "2"
      }
    }
  },
  "headers": {
    "type": "object",
    "properties": {
      "new": {
        "type": "string",
        "description": "2"
      }
    }
  },
  "timeoutSeconds": 20
}'
```

--------------------------------

### cURL request for List contacts

Source: https://docs.superu.ai/api-reference/contacts/list-contacts

Example cURL command to retrieve a list of contacts using the SuperU API key.

```bash
curl --request GET \
  --url https://voip-middlware.superu.ai/contact/list?page=1&limit=10&search_query=ava \
  --header 'superU-Api-Key: YOUR_SUPERU_API_KEY'
```