# Endpoints

Endpoints define where inbound calls are routed. They can point to AI voice providers (ElevenLabs, Vapi, Retell) or custom webhook URLs.

Base URL: `https://api.krosai.com/v1/endpoints`

## Endpoint Types

| Type      | Description       | Use Case                          |
| --------- | ----------------- | --------------------------------- |
| `agent`   | AI voice provider | ElevenLabs, Vapi, Retell, LiveKit |
| `webhook` | HTTP webhook      | Custom server handling            |

## List Endpoints

Retrieve all endpoints for your organization.

GET /endpoints

### Query Parameters

| Parameter | Type    | Description                            |
| --------- | ------- | -------------------------------------- |
| `type`    | string  | Filter by type: `agent`, `webhook`     |
| `status`  | string  | Filter by status: `active`, `inactive` |
| `limit`   | integer | Number of results (default: 50)        |
| `offset`  | integer | Pagination offset                      |

### Request

```bash
curl -X GET "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key"
```

### Response

```json
{
  "endpoints": [
    {
      "id": "ep_abc123",
      "name": "Customer Support Agent",
      "type": "agent",
      "url": "sip:agent@sip.rtc.elevenlabs.io",
      "status": "active",
      "provider_config": {
        "provider": "elevenlabs",
        "agent_id": "agent_xyz"
      },
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-01-10T10:00:00Z"
    },
    {
      "id": "ep_def456",
      "name": "Custom Handler",
      "type": "webhook",
      "url": "https://api.yourapp.com/call-handler",
      "status": "active",
      "secret": "whsec_...",
      "created_at": "2025-01-09T15:00:00Z",
      "updated_at": "2025-01-09T15:00:00Z"
    }
  ],
  "total": 2
}
```

## Get Endpoint

Retrieve details for a specific endpoint.

GET /endpoints/{id}

### Request

```bash
curl -X GET "https://api.krosai.com/v1/endpoints/ep_abc123" \
  -H "x-api-key: kros_live_your_key"
```

### Response

```json
{
  "id": "ep_abc123",
  "name": "Customer Support Agent",
  "type": "agent",
  "url": "sip:agent@sip.rtc.elevenlabs.io",
  "status": "active",
  "provider_config": {
    "provider": "elevenlabs",
    "agent_id": "agent_xyz"
  },
  "phone_numbers": [
    {
      "id": "pn_123",
      "number": "+2348012345678"
    }
  ],
  "call_count_24h": 45,
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z"
}
```

## Create Endpoint

Create a new endpoint for call routing.

POST /endpoints

### Request Body

| Field             | Type   | Required   | Description                     |
| ----------------- | ------ | ---------- | ------------------------------- |
| `name`            | string | Yes        | Descriptive name                |
| `type`            | string | Yes        | `agent` or `webhook`            |
| `url`             | string | Yes        | SIP URI or webhook URL          |
| `provider_config` | object | For agents | Provider-specific configuration |

### Agent Endpoint (ElevenLabs)

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ElevenLabs Support Agent",
    "type": "agent",
    "url": "sip:agent@sip.rtc.elevenlabs.io",
    "provider_config": {
      "provider": "elevenlabs",
      "agent_id": "your-elevenlabs-agent-id"
    }
  }'
```

### Agent Endpoint (Vapi)

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vapi Sales Assistant",
    "type": "agent",
    "url": "sip:assistant@sip.vapi.ai",
    "provider_config": {
      "provider": "vapi",
      "assistant_id": "your-vapi-assistant-id"
    }
  }'
```

### Agent Endpoint (Retell)

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retell Booking Agent",
    "type": "agent",
    "url": "sip:agent@retell.ai",
    "provider_config": {
      "provider": "retell",
      "agent_id": "your-retell-agent-id"
    }
  }'
```

### Webhook Endpoint

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Call Handler",
    "type": "webhook",
    "url": "https://api.yourapp.com/inbound-call"
  }'
```

### Response

```json
{
  "id": "ep_new789",
  "name": "ElevenLabs Support Agent",
  "type": "agent",
  "url": "sip:agent@sip.rtc.elevenlabs.io",
  "status": "active",
  "provider_config": {
    "provider": "elevenlabs",
    "agent_id": "your-elevenlabs-agent-id"
  },
  "secret": "whsec_abc123...",
  "created_at": "2025-01-10T12:00:00Z"
}
```

{% hint style="info" %}
For webhook endpoints, a signing secret is automatically generated. Use this to verify webhook payloads.
{% endhint %}

## Update Endpoint

Update an existing endpoint.

PATCH /endpoints/{id}

### Request Body

| Field             | Type   | Description                    |
| ----------------- | ------ | ------------------------------ |
| `name`            | string | New name                       |
| `url`             | string | New SIP URI or webhook URL     |
| `status`          | string | `active` or `inactive`         |
| `provider_config` | object | Updated provider configuration |

### Request

```bash
curl -X PATCH "https://api.krosai.com/v1/endpoints/ep_abc123" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Support Agent",
    "status": "active"
  }'
```

### Response

```json
{
  "id": "ep_abc123",
  "name": "Updated Support Agent",
  "status": "active",
  "updated_at": "2025-01-10T13:00:00Z"
}
```

## Delete Endpoint

Delete an endpoint. Phone numbers attached to this endpoint will need to be reconfigured.

DELETE /endpoints/{id}

### Request

```bash
curl -X DELETE "https://api.krosai.com/v1/endpoints/ep_abc123" \
  -H "x-api-key: kros_live_your_key"
```

### Response

```json
{
  "success": true,
  "message": "Endpoint deleted successfully"
}
```

{% hint style="warning" %}
Deleting an endpoint will cause any attached phone numbers to stop receiving calls until a new endpoint is assigned.
{% endhint %}

## Provider Configuration

<details>

<summary>ElevenLabs</summary>

```json
{
  "provider": "elevenlabs",
  "agent_id": "your-agent-id"
}
```

The `agent_id` is found in your ElevenLabs Conversational AI dashboard.

</details>

<details>

<summary>Vapi</summary>

```json
{
  "provider": "vapi",
  "assistant_id": "your-assistant-id"
}
```

</details>

<details>

<summary>Retell</summary>

```json
{
  "provider": "retell",
  "agent_id": "your-agent-id"
}
```

</details>

<details>

<summary>LiveKit</summary>

```json
{
  "provider": "livekit",
  "livekit_agent_name": "my-voice-agent",
  "livekit_sip_trunk_id": "trunk-id",
  "livekit_sip_uri": "sip:xxxxx.sip.livekit.cloud"
}
```

</details>

## Webhook Payload

When using webhook endpoints, KrosAI sends HTTP POST requests with call information:

```json
{
  "event": "call.incoming",
  "call_id": "call_xyz789",
  "from_number": "+14155551234",
  "to_number": "+2348012345678",
  "timestamp": "2025-01-10T12:00:00Z",
  "metadata": {}
}
```

### Verifying Webhook Signatures

```typescript
import crypto from 'crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}
```

## Code Examples

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Create an ElevenLabs endpoint
async function createElevenLabsEndpoint(name: string, agentId: string) {
  const response = await fetch('https://api.krosai.com/v1/endpoints', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.KROSAI_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name,
      type: 'agent',
      url: 'sip:agent@sip.rtc.elevenlabs.io',
      provider_config: {
        provider: 'elevenlabs',
        agent_id: agentId,
      },
    }),
  });
  
  return response.json();
}

// Create a webhook endpoint
async function createWebhookEndpoint(name: string, webhookUrl: string) {
  const response = await fetch('https://api.krosai.com/v1/endpoints', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.KROSAI_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name,
      type: 'webhook',
      url: webhookUrl,
    }),
  });
  
  const data = await response.json();
  // Save data.secret for webhook verification
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

def create_endpoint(name, endpoint_type, url, provider_config=None):
    payload = {
        'name': name,
        'type': endpoint_type,
        'url': url
    }
    
    if provider_config:
        payload['provider_config'] = provider_config
    
    response = requests.post(
        'https://api.krosai.com/v1/endpoints',
        headers={
            'x-api-key': os.environ['KROSAI_API_KEY'],
            'Content-Type': 'application/json'
        },
        json=payload
    )
    
    return response.json()

# Create ElevenLabs endpoint
endpoint = create_endpoint(
    name='Support Agent',
    endpoint_type='agent',
    url='sip:agent@sip.rtc.elevenlabs.io',
    provider_config={
        'provider': 'elevenlabs',
        'agent_id': 'your-agent-id'
    }
)
```

{% endtab %}
{% endtabs %}

##


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/voice/endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.