REST API v1.0
API modern cu arhitectură RESTful, răspunsuri JSON și autentificare securizată prin API keys.
Base URL:
https://api.kallina.ai/v1Protocol: HTTPS only
Format: JSON
Auth: API Key (Bearer token)
Primul tău request
curl -X GET \ https://api.kallina.ai/v1/agents \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Autentificare
Toate request-urile către API necesită un API key valid în header-ul Authorization.
Obținerea API Key
- 1. Loghează-te în Dashboard-ul Kallina.ai
- 2. Navighează la Settings → API Keys
- 3. Click "Generate New Key"
- 4. Copiază și salvează cheia securizat
Format Header
Authorization: Bearer kallina_sk_live_xyz123...⚠ Nu expune niciodată API key-ul în cod client-side
Endpoint-uri Principale
GET
/agentsListează toți agenții AI din contul tău
Request
GET /v1/agents Authorization: Bearer YOUR_API_KEY Query Parameters: - limit: int (default: 20) - page: int (default: 1) - status: string (active|inactive)
Response
{
"data": [
{
"id": "agent_123",
"name": "Ana Sales",
"voice": "ro-RO-female-warm",
"status": "active",
"created_at": "2025-01-01T00:00:00Z"
}
],
"meta": {
"total": 1,
"page": 1,
"limit": 20
}
}POST
/agentsCreează un agent AI nou
Request Body
{
"name": "Ana Restaurant",
"voice": "ro-RO-female-warm",
"personality": "professional-friendly",
"industry": "restaurant",
"instructions": "Tu ești Ana...",
"integrations": {
"calendar": {
"provider": "google",
"calendar_id": "primary"
}
}
}Response
{
"id": "agent_456",
"name": "Ana Restaurant",
"voice": "ro-RO-female-warm",
"status": "active",
"phone_number": "+40800123456",
"webhook_url": null,
"created_at": "2025-01-23T10:30:00Z"
}POST
/callsInițiază un apel cu un agent AI
Request Body
{
"agent_id": "agent_456",
"phone_number": "+40712345678",
"context": {
"customer_name": "Ion Popescu",
"previous_orders": ["pizza"],
"preferred_time": "evening"
},
"webhook_url": "https://your-app.com/webhook"
}Response
{
"id": "call_789",
"agent_id": "agent_456",
"phone_number": "+40712345678",
"status": "initiated",
"started_at": "2025-01-23T10:35:00Z",
"estimated_duration": 120
}Gestionarea Erorilor
Coduri de Status HTTP
200OK - Request reușit
201Created - Resursa creată
400Bad Request - Date invalide
401Unauthorized - API key invalid
429Rate Limited - Prea multe request-uri
500Server Error - Eroare internă
Format Răspuns Eroare
{
"error": {
"code": "invalid_phone_number",
"message": "Numărul de telefon nu este valid",
"details": {
"field": "phone_number",
"provided": "+407123",
"expected": "E.164 format"
},
"request_id": "req_xyz123"
}
}Tip: Folosește request_id când contactezi suportul pentru debugging
Rate Limiting
Limite Curente
Free Tier100 req/min
Developer1,000 req/min
Business5,000 req/min
EnterpriseCustom
Headers Răspuns
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1642780800 X-RateLimit-Retry-After: 60
Limit: Numărul maxim de request-uri pe minut
Remaining: Request-uri rămase în fereastra curentă
Reset: Timestamp când se resetează (Unix)
Retry-After: Secunde până la reset
Webhooks
Configurare Webhooks
Webhooks-urile îți permit să primești notificări în timp real pentru evenimente importante.
Tipuri de Evenimente
call.startedcall.endedagent.action_completedconversation.updatedExemplu Payload
{
"event": "call.ended",
"timestamp": "2025-01-23T10:30:00Z",
"data": {
"call_id": "call_789",
"agent_id": "agent_456",
"duration": 180,
"outcome": "appointment_booked",
"actions": [
{
"type": "calendar_booking",
"status": "completed",
"data": {
"date": "2025-01-25",
"time": "14:00"
}
}
]
}
}Securitatea Webhooks
Verificarea Semnăturii
Fiecare webhook include un header X-Kallina-Signature pentru verificarea autenticității.
X-Kallina-Signature: sha256=abc123...
Verificare în Node.js
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Testarea API-ului
API Explorer Interactiv
Testează toate endpoint-urile direct din browser cu datele tale reale
GET
/agents