Get started

Quickstart

Create an agent, place a simulated call and read the result.

This walkthrough needs nothing but an account. It uses the mock engine, which plays a scripted conversation without dialling anyone, so you can run it safely.

1. Get an API key

Sign up in the dashboard, then open Developers and create a key. Or do both through the API:

bash
curl -X POST https://api.kshyamai.space/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Bank", "email": "dev@example.test", "password": "a-long-passphrase-42"}'

The response has a session token (it starts with vs- and lasts 7 days). Use it once to create an API key:

bash
curl -X POST https://api.kshyamai.space/auth/api-keys \
  -H "Authorization: Bearer vs-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart"}'
json
{
  "id": "5f0c2f0e-8a57-4a0e-9a53-2f8b3f1f5c11",
  "name": "quickstart",
  "prefix": "vk-01234",
  "key": "vk-0123456789abcdef0123456789abcdef"
}

The key is shown only this once. Store it; the platform keeps only a hash. The other fields in the response are described in Auth.

2. Create an agent

An agent is a configuration plus its prompts. This one asks the mock engine to run it, whatever the deployment's default engine is.

bash
curl -X POST https://api.kshyamai.space/v2/agent \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "Payment reminder",
      "agent_welcome_message": "Hello {customer_name}, this is a reminder call from Example Bank.",
      "engine": "mock",
      "tasks": [
        {
          "task_type": "conversation",
          "tools_config": {
            "llm_agent": {
              "agent_type": "simple_llm_agent",
              "agent_flow_type": "streaming",
              "llm_config": {"provider": "openai", "model": "gpt-4o-mini"}
            },
            "synthesizer": {
              "provider": "elevenlabs",
              "stream": true,
              "buffer_size": 250,
              "audio_format": "wav",
              "provider_config": {"voice": "Nila", "voice_id": "V9LCAAi4tTlqe9JadbCo", "model": "eleven_turbo_v2_5"}
            },
            "transcriber": {"provider": "deepgram", "model": "nova-2", "language": "en", "stream": true},
            "input": {"provider": "twilio", "format": "wav"},
            "output": {"provider": "twilio", "format": "wav"}
          },
          "toolchain": {"execution": "parallel", "pipelines": [["transcriber", "llm", "synthesizer"]]},
          "task_config": {"hangup_after_silence": 10, "call_terminate": 300}
        }
      ]
    },
    "agent_prompts": {
      "task_1": {"system_prompt": "You remind the customer that a payment is due on {due_date}. Be brief and polite."}
    }
  }'

The response contains the new agent_id.

Note: The provider and model names in an agent are stored as you send them. With the mock engine they only affect the cost estimate. On a live call, which models actually run depends on the voice engine of your deployment: see Models.

3. Place a call

bash
curl -X POST https://api.kshyamai.space/call \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-call-1" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426655440000",
    "recipient_phone_number": "+919876500000",
    "user_data": {"customer_name": "Asha", "due_date": "5 November"}
  }'
json
{"message": "done", "status": "queued", "execution_id": "0b0f4e5c-7c0a-4d4e-bb2b-6b3b8a1f2c9d"}

user_data fills the {placeholders} in the welcome message and the prompt. The Idempotency-Key header makes the request safe to send again: see Idempotency.

4. Read the result

Poll the execution until its status is final, or receive it by webhook.

bash
curl https://api.kshyamai.space/executions/0b0f4e5c-7c0a-4d4e-bb2b-6b3b8a1f2c9d \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

A finished execution has status: "completed", a transcript, a total_cost with a cost_breakdown, and a recording URL in telephony_data. The full shape is in Executions.

What to try next