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

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

Response

{
  "endpoints": [
    {
      "id": "ep_abc123",
      "name": "Customer Support Agent",
      "type": "agent",
      "url": "sip:[email protected]",
      "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

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

Response

{
  "id": "ep_abc123",
  "name": "Customer Support Agent",
  "type": "agent",
  "url": "sip:[email protected]",
  "status": "active",
  "provider_config": {
    "provider": "elevenlabs",
    "agent_id": "agent_xyz"
  },
  "phone_numbers": [
    {
      "id": "pn_123",
      "number": "[phone]"
    }
  ],
  "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)

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:[email protected]",
    "provider_config": {
      "provider": "elevenlabs",
      "agent_id": "your-elevenlabs-agent-id"
    }
  }'

Agent Endpoint (Vapi)

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:[email protected]",
    "provider_config": {
      "provider": "vapi",
      "assistant_id": "your-vapi-assistant-id"
    }
  }'

Agent Endpoint (Retell)

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:[email protected]",
    "provider_config": {
      "provider": "retell",
      "agent_id": "your-retell-agent-id"
    }
  }'

Webhook Endpoint

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

{
  "id": "ep_new789",
  "name": "ElevenLabs Support Agent",
  "type": "agent",
  "url": "sip:[email protected]",
  "status": "active",
  "provider_config": {
    "provider": "elevenlabs",
    "agent_id": "your-elevenlabs-agent-id"
  },
  "secret": "whsec_abc123...",
  "created_at": "2025-01-10T12:00:00Z"
}

For webhook endpoints, a signing secret is automatically generated. Use this to verify webhook payloads.

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

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

{
  "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

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

Response

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

Deleting an endpoint will cause any attached phone numbers to stop receiving calls until a new endpoint is assigned.

Provider Configuration

ElevenLabs

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

The agent_id is found in your ElevenLabs Conversational AI dashboard.

Vapi

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

Retell

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

LiveKit

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

Webhook Payload

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

{
  "event": "call.incoming",
  "call_id": "call_xyz789",
  "from_number": "[phone]",
  "to_number": "[phone]",
  "timestamp": "2025-01-10T12:00:00Z",
  "metadata": {}
}

Verifying Webhook Signatures

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

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:[email protected]',
      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;
}

Python