Build your first
voice session.

Use a Swarit API-audience OAuth access token with the vn:ai:execute scope. Keep that token on your backend; send only temporary session connection credentials to your browser.

Set SWARIT_BASE_URL to your enabled Swarit backend origin and SWARIT_ACCESS_TOKEN to your access token. The marketing website does not serve these API routes. Public credential onboarding is not yet available.

Your workspace needs a funded INR API wallet. Existing Cloud subscription credits do not automatically fund it.

No saved agent is required. Supply instructions and an idempotency key of 8–200 characters. Reuse the same key and request when retrying a creation; use a new key for a new conversation.

curl "$SWARIT_BASE_URL/api/voice/v1/sessions" \
  -H "Authorization: Bearer $SWARIT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: appointment-session-001" \
  -d '{
    "instructions": "Help the caller arrange an appointment.",
    "language": "en",
    "voice": "female",
    "reflex_answers": true,
    "steps": null,
    "max_duration_seconds": 600
  }'

Save the returned id. A new session starts in preparing; poll its status before requesting connection credentials.

instructions

Required, 10–8,000 characters. Describe the purpose and behavior of the voice agent.

language / voice

Default: English (en) and female. Voice also accepts male.

reflex_answers

Defaults to true. Set false to skip local reflex replies and let the backend supply the response.

steps

Defaults to null for an open conversation. Supply a validated conversation graph for guided steps; see the exact schema in the backend OpenAPI specification. Steps and reflex answers work independently.

max_duration_seconds

30–3,600 seconds; default 600. This resource limit starts at media readiness and can include model warmup. Billable time starts only once the caller is connected and the model is ready.

1. Poll GET /sessions/{id} until status is ready.
2. Request POST /sessions/{id}/connection from your backend.
3. Use the returned LiveKit transport credentials in your client. Publish microphone audio and subscribe to the agent’s audio track.
4. When finished, request DELETE /sessions/{id}.

Join tokens expire after ten minutes; this controls joining, not conversation duration. Retrieval, connection, and termination must use the same OAuth client and workspace that created the session.

Handle microphone permission failures and terminal session states in your UI. Disconnects, duration limits, runtime failures, or failed billing heartbeats can close a session.

Supply up to 20 tools when creating a session. Swarit’s existing reasoning model chooses a tool; your backend executes it and sends the result back. The agent then continues speaking.

{
  "tools": [
    {
      "name": "check_availability",
      "description": "Find available appointments for a date.",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Date in YYYY-MM-DD format"
          }
        },
        "required": [
          "date"
        ],
        "additionalProperties": false
      }
    }
  ]
}

Add this tools array to the session creation request. While the conversation runs, poll GET /sessions/{id}/tool-calls from your backend, for example every 250–500 milliseconds. Run the handler matching the returned name, using the supplied arguments.

{
  "tool_call_id": "ID returned by tool-calls",
  "result": {
    "output": {
      "available_times": [
        "10:00",
        "11:30"
      ]
    }
  }
}

POST this result to /sessions/{id}/tool-results. Return { "error": "Calendar unavailable" } as the result when execution fails. Results may contain up to 32 KiB and must arrive within 30 seconds.

Polling may return the same request again. Deduplicate actions durably by tool-call ID, including across workers. Identical result retries are accepted; conflicting, expired, or cancelled results return 409. An interruption cannot undo an action your backend already performed.

Use only known handlers, validate business permissions, and obtain any required user confirmation before performing actions. Keep credentials on your backend. The session billing clock continues while waiting for tools.

Tool schemas support object, array, string, number, integer, and boolean types; properties, required fields, descriptions, items, and enums. Objects require additionalProperties: false. Remote schema references and unrestricted objects are unsupported.

Prompts and tools are configured at session creation; start a new session to change them. Model selection remains server-controlled. Developer tools do not grant access to internal workspace capabilities.

Realtime billing follows connected conversation duration, measured in milliseconds. A 90-second conversation costs ₹3. Amounts round up once to a paise.

A session reserves its maximum possible charge from your INR wallet. The default ten-minute limit reserves ₹20. Actual usage is charged and unused reserved funds are released when the session ends.

Workspace owners and admins with vn:billing:write can read GET /wallet, create a Razorpay order with POST /wallet/topups, and confirm payment with POST /wallet/topups/confirm. Top-up amounts use integer paise; ₹500 is 50000. Payment configuration must be enabled before purchases are available.

All paths below are relative to /api/voice/v1 on your Swarit backend.

POST /sessions

Prepare a session. Returns 202 for a new session or 200 for a replay. Read the id and status from the response.

GET /sessions/{id}

Poll session status until ready. Stop polling when the session ends or fails.

POST /sessions/{id}/connection

After readiness, obtain transport credentials. Returns session_id, transport, and expires_in.

DELETE /sessions/{id}

Request termination. Returns 202 with status ending.

GET /sessions/{id}/tool-calls

Poll pending tool requests from your backend. Each request has an id, name, arguments, and expires_at.

POST /sessions/{id}/tool-results

Submit output or error for a pending tool call. Identical retries are accepted.

GET /pricing

Read current INR rates and service availability.

GET /openapi.json

Read the machine-readable API specification.

Failed requests return an error object with code and message. Check the HTTP status before using the response. A disabled API or unavailable runtime returns 503; do not repeatedly create new sessions to retry.

Standalone STT and TTS: coming soon. Their public endpoints are unavailable while we update infrastructure and architecture.