LionVoice API — complete reference

This document describes the entire LionVoice platform API. It is written so that a human or an AI agent reading only this page can fully operate a LionVoice account: create voice assistants, upload knowledge, connect phone numbers, read calls and transcripts, manage API keys and billing.

1. Quick start

Base URL and authentication — everything below uses them:

• Base URL: https://api.lionvoice.app/api/v1
• Auth: every request (except /ping) needs header Authorization: Bearer lv_live_…
• Body format: JSON (Content-Type: application/json)
• Create a key: dashboard → API keys → Create new key. The key is shown once.

# Check the API is alive (no auth needed)
curl https://api.lionvoice.app/api/v1/ping

# Your account snapshot
curl -H "Authorization: Bearer lv_live_…" https://api.lionvoice.app/api/v1/tenant

2. Core concepts

3. Authentication

# Recommended — Authorization header
Authorization: Bearer lv_live_xxxxxxxxxxxxxxxx

# Alternative — custom header
X-LV-Api-Key: lv_live_xxxxxxxxxxxxxxxx

• Keys are tenant-scoped: they can only see and modify their own tenant's data.
• Revoked keys stop working immediately.
• HTTPS only. Never put the key in a URL.

4. Endpoints

POSTGETPATCHDELETE /agents — assistants

GET /agents — list all assistants with phone and file counts.

curl -H "Authorization: Bearer lv_live_…" https://api.lionvoice.app/api/v1/agents

POST /agents — create an assistant.

curl -X POST https://api.lionvoice.app/api/v1/agents \
  -H "Authorization: Bearer lv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales assistant",
    "prompt": "You are the phone assistant for … . Address the customer as you. Be brief and factual.",
    "first_message": "Hi, I am your LionVoice assistant. How can I help?",
    "voice": "Sari",
    "language": "lt",
    "max_duration_sec": 300,
    "voicemail_action": "hangup",
    "webhook_url": "https://example.com/hooks/lionvoice"
  }'

Fields: name (required) · prompt (system prompt, plain text) · first_message (spoken first when the agent answers) · voice (Sari|Emma|Liutas|Aurora) · language (lt|lv|en|ru) · max_duration_sec (30–1800, default 300) · voicemail_action (hangup|leave_message) · webhook_url (HTTPS; receives call events).

PATCH /agents/{id} — partial update (any subset of the fields above, plus status: active|paused).

curl -X PATCH https://api.lionvoice.app/api/v1/agents/2 \
  -H "Authorization: Bearer lv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Updated system prompt…"}'

GET /agents/{id} — full assistant incl. attached files. DELETE /agents/{id} — delete (numbers and files detach, they are not deleted).

GETPOSTPATCHDELETE /files — knowledge base

POST /files — create a knowledge file (text, max 500 KB). PATCH /files/{id} — update filename/content/agent assignment. DELETE /files/{id} — remove.

curl -X POST https://api.lionvoice.app/api/v1/files \
  -H "Authorization: Bearer lv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "prices.txt",
    "content": "Internet 8.99 EUR/month\nModem deposit 36 EUR\nDelivery: free to parcel locker",
    "agent_id": 2
  }'

GETPOSTPATCHDELETE /phone-numbers

POST /phone-numbers — register a DID you own (E.164). PATCH /phone-numbers/{id} — assign to an assistant ({"agent_id": 2} or {"agent_id": null}), set label or inbound_enabled. DELETE — un-register from LionVoice (your provider keeps the number).

curl -X PATCH https://api.lionvoice.app/api/v1/phone-numbers/1 \
  -H "Authorization: Bearer lv_live_…" \
  -d '{"agent_id": 2}'

GET /calls — calls and transcripts

# List (newest first)
curl -H "Authorization: Bearer lv_live_…" "https://api.lionvoice.app/api/v1/calls?limit=50"

# One call with full transcript
curl -H "Authorization: Bearer lv_live_…" "https://api.lionvoice.app/api/v1/calls/CALL-UUID"

Call object: call_uuid, direction (inbound/outbound), from_number, to_number, start_utc, end_utc, billable_seconds, cost_eur, turn_count, amd_result (human/voicemail/unknown), status, transcript, summary.

GET /analytics · /usage · /tenant

# Daily stats for the last N days (1–90)
curl -H "Authorization: Bearer lv_live_…" "https://api.lionvoice.app/api/v1/analytics?days=14"

# Monthly usage for a calendar month
curl -H "Authorization: Bearer lv_live_…" "https://api.lionvoice.app/api/v1/usage?year=2026&month=9"

POSTDELETE /keys

# Create a key (label is for your own bookkeeping)
curl -X POST https://api.lionvoice.app/api/v1/keys \
  -H "Authorization: Bearer lv_live_…" \
  -d '{"label": "my-automation-agent"}'

# Revoke
curl -X DELETE "https://api.lionvoice.app/api/v1/keys?id=12"

POST /topup

curl -X POST https://api.lionvoice.app/api/v1/topup \
  -H "Authorization: Bearer lv_live_…" \
  -d '{"amount_eur": 50}'
# → {"ok": true, "checkout_url": "https://checkout.stripe.com/…"} — redirect the user there

5. Errors

All error responses share the shape {"ok": false, "error": "…"}.

6. Migration guide — moving an assistant from another voice platform

Bring an existing assistant over in four steps. Typical migration takes a few minutes per assistant:

1. Copy the system prompt from your old platform and POST it to /agents as prompt. Prompts are plain text — paste them 1:1. If the old platform used placeholders for its own tools, keep the wording but make sure referenced tools exist (step 3).
2. Copy the knowledge base: export documents/FAQs from the old platform and POST each to /files (one file per topic), then assign them with agent_id.
3. Recreate tools: any HTTP/webhook tools the old assistant called should be exposed through your webhook_url — the LionVoice engine sends call events and can receive your instructions there.
4. Connect numbers: point your SIP/DID at LionVoice (or ask support to provision numbers) and PATCH /phone-numbers/{id} with the assistant id. Test with an inbound call.

7. Complete recipes

7.1 Full setup from zero

# 1. Create the assistant
curl -X POST .../agents -d '{"name":"Front desk","prompt":"You are…","voice":"Sari","language":"lt"}'
# → {"ok":true,"id":2}

# 2. Upload knowledge
curl -X POST .../files -d '{"filename":"faq.txt","content":"…","agent_id":2}'

# 3. Register + assign your number
curl -X POST .../phone-numbers -d '{"number_e164":"+37052636333"}'
curl -X PATCH .../phone-numbers/1 -d '{"agent_id":2}'

# 4. Done — inbound calls to +37052636333 are answered by "Front desk".

7.2 Daily monitoring loop (for an automation agent)

# every hour:
GET /calls?limit=20          # new calls + transcripts
GET /analytics?days=1        # yesterday's minutes and costs
GET /tenant                  # wallet balance; if < €10 → alert the owner