> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SLNG Voice Agent API examples

> Code samples for the SLNG Voice Agent API in JavaScript and Python. Create, list, update, test, and delete voice agents through the agent lifecycle.

Working code for the agent lifecycle. For prompt design, tool configuration, and template variables, see [Configuring voice agents](/examples/agents-config).

## Placeholders

Every snippet below uses these placeholders. Replace them before running the code.

| Placeholder                                         | Replace with                                                                                                                     |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `SLNG_API_KEY`                                      | An SLNG key from [app.slng.ai/api-keys](https://app.slng.ai/api-keys). Use it as the bearer token in the `Authorization` header. |
| `AGENT_ID` / `550e8400-e29b-41d4-a716-446655440000` | The agent's UUID returned by `POST /v1/agents`                                                                                   |
| `region: "eu-central"`                              | A Voice Agents logical region. See [Agent regions](/voice-agents#agent-regions)                                                  |

## Create an agent

<CodeGroup>
  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.agents.slng.ai/v1/agents", {
    method: "POST",
    headers: {
      Authorization: "Bearer SLNG_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Appointment Reminder",
      system_prompt:
        "You are a friendly appointment reminder for {{clinic_name}}. " +
        "Confirm the patient upcoming visit or help them reschedule. " +
        "Keep responses to one or two sentences.",
      greeting: "Hi {{patient_name}}, this is a reminder from {{clinic_name}} about your upcoming appointment.",
      language: "en",
      region: "eu-central",
      models: {
        stt: "slng/deepgram/nova:3-en",
        llm: "groq/openai/gpt-oss-120b",
        tts: "slng/deepgram/aura:2-en",
        tts_voice: "aura-2-thalia-en",
      },
      template_defaults: {
        clinic_name: "Downtown Health Clinic",
        patient_name: "there",
      },
    }),
  });

  const agent = await resp.json();
  console.log(agent.id);
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.agents.slng.ai/v1/agents",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
      json={
          "name": "Appointment Reminder",
          "system_prompt": (
              "You are a friendly appointment reminder for {{clinic_name}}. "
              "Confirm the patient upcoming visit or help them reschedule. "
              "Keep responses to one or two sentences."
          ),
          "greeting": "Hi {{patient_name}}, this is a reminder from {{clinic_name}} about your upcoming appointment.",
          "language": "en",
          "region": "eu-central",
          "models": {
              "stt": "slng/deepgram/nova:3-en",
              "llm": "groq/openai/gpt-oss-120b",
              "tts": "slng/deepgram/aura:2-en",
              "tts_voice": "aura-2-thalia-en",
          },
          "template_defaults": {
              "clinic_name": "Downtown Health Clinic",
              "patient_name": "there",
          },
      },
  )

  agent = resp.json()
  print(agent["id"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.agents.slng.ai/v1/agents \
    -H "Authorization: Bearer SLNG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Appointment Reminder",
      "system_prompt": "You are a friendly appointment reminder for {{clinic_name}}. Confirm the patient upcoming visit or help them reschedule. Keep responses to one or two sentences.",
      "greeting": "Hi {{patient_name}}, this is a reminder from {{clinic_name}} about your upcoming appointment.",
      "language": "en",
      "region": "eu-central",
      "models": {
        "stt": "slng/deepgram/nova:3-en",
        "llm": "groq/openai/gpt-oss-120b",
        "tts": "slng/deepgram/aura:2-en",
        "tts_voice": "aura-2-thalia-en"
      },
      "template_defaults": {
        "clinic_name": "Downtown Health Clinic",
        "patient_name": "there"
      }
    }'
  ```
</CodeGroup>

## Test with a web session

Web sessions let you talk to your agent from a browser. No phone number or SIP trunk required. The response includes LiveKit credentials you can use with any [LiveKit client SDK](https://docs.livekit.io/client-sdk-js/).

<CodeGroup>
  ```javascript JavaScript theme={null}
  const resp = await fetch(
    `https://api.agents.slng.ai/v1/agents/${agent.id}/web-sessions`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer SLNG_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        arguments: { patient_name: "Maria", clinic_name: "Greenfield Family Medicine" },
      }),
    },
  );

  const session = await resp.json();
  // session.livekit_url:   WebSocket URL to connect to
  // session.livekit_token: access token for the room
  // session.room_name:     LiveKit room name
  // session.call_id:       use this to look up the call later
  // session.max_session_seconds: how long the session stays open
  ```

  ```python Python theme={null}
  resp = requests.post(
      f"https://api.agents.slng.ai/v1/agents/{agent['id']}/web-sessions",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
      json={
          "arguments": {"patient_name": "Maria", "clinic_name": "Greenfield Family Medicine"},
      },
  )

  session = resp.json()
  # session["livekit_url"]:   WebSocket URL to connect to
  # session["livekit_token"]: access token for the room
  # session["room_name"]:     LiveKit room name
  # session["call_id"]:       use this to look up the call later
  # session["max_session_seconds"]: how long the session stays open
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.agents.slng.ai/v1/agents/AGENT_ID/web-sessions \
    -H "Authorization: Bearer SLNG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "participant_name": "Test user",
      "arguments": {
        "patient_name": "Maria"
      }
    }'
  ```
</CodeGroup>

Both fields are optional. `arguments` overrides `template_defaults` on the agent, and `participant_name` sets a display name in the LiveKit room.

## Update an agent

PATCH updates only the fields you send. Use PUT if you want to replace the entire configuration.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const resp = await fetch(
    `https://api.agents.slng.ai/v1/agents/${agent.id}`,
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer SLNG_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        greeting: "Hello {{patient_name}}, thanks for picking up.",
        models: {
          stt: "slng/deepgram/nova:3-en",
          llm: "groq/openai/gpt-oss-120b",
          tts: "slng/deepgram/aura:2-en",
          tts_voice: "aura-2-thalia-en",
          llm_kwargs: { temperature: 0.3 },
        },
      }),
    },
  );

  const updated = await resp.json();
  ```

  ```python Python theme={null}
  resp = requests.patch(
      f"https://api.agents.slng.ai/v1/agents/{agent['id']}",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
      json={
          "greeting": "Hello {{patient_name}}, thanks for picking up.",
          "models": {
              "stt": "slng/deepgram/nova:3-en",
              "llm": "groq/openai/gpt-oss-120b",
              "tts": "slng/deepgram/aura:2-en",
              "tts_voice": "aura-2-thalia-en",
              "llm_kwargs": {"temperature": 0.3},
          },
      },
  )

  updated = resp.json()
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.agents.slng.ai/v1/agents/AGENT_ID \
    -H "Authorization: Bearer SLNG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "greeting": "Hello {{patient_name}}, thanks for picking up.",
      "models": {
        "stt": "slng/deepgram/nova:3-en",
        "llm": "groq/openai/gpt-oss-120b",
        "tts": "slng/deepgram/aura:2-en",
        "tts_voice": "aura-2-thalia-en",
        "llm_kwargs": { "temperature": 0.3 }
      }
    }'
  ```
</CodeGroup>

## Duplicate an agent

Use duplication when you want to copy an existing agent configuration as-is, including prompts,
models, tools, template defaults, selected region, and outbound telephony settings.

The duplicate does not copy call history or the inbound connection.

After duplicating an agent:

* Reconnect inbound routing if the duplicate should receive calls.
* Verify the outbound trunk before dispatching calls.
* Test the duplicate with a web session or a test call.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const duplicated = await fetch(
    `https://api.agents.slng.ai/v1/agents/${agent.id}/duplicate`,
    {
      method: "POST",
      headers: {
        Authorization: "Bearer SLNG_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: `${agent.name} Copy`,
      }),
    },
  ).then((r) => r.json());

  console.log(duplicated.id);
  ```

  ```python Python theme={null}
  duplicated = requests.post(
      f"https://api.agents.slng.ai/v1/agents/{agent['id']}/duplicate",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
      json={
          "name": f"{agent['name']} Copy",
      },
  ).json()

  print(duplicated["id"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.agents.slng.ai/v1/agents/AGENT_ID/duplicate \
    -H "Authorization: Bearer SLNG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Appointment Reminder Copy"
    }'
  ```
</CodeGroup>

## List and inspect agents

<CodeGroup>
  ```javascript JavaScript theme={null}
  // List all agents
  const agents = await fetch("https://api.agents.slng.ai/v1/agents", {
    headers: { Authorization: "Bearer SLNG_API_KEY" },
  }).then((r) => r.json());

  for (const a of agents) {
    console.log(`${a.name} (${a.id})`);
  }

  // Get a single agent and check its template variables
  const agent = await fetch(`https://api.agents.slng.ai/v1/agents/${agents[0].id}`, {
    headers: { Authorization: "Bearer SLNG_API_KEY" },
  }).then((r) => r.json());

  console.log(agent.template_variables);
  // { clinic_name: { required: true, default: "Downtown Health Clinic" }, ... }
  ```

  ```python Python theme={null}
  # List all agents
  agents = requests.get(
      "https://api.agents.slng.ai/v1/agents",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
  ).json()

  for a in agents:
      print(f"{a['name']} ({a['id']})")

  # Get a single agent and check its template variables
  agent = requests.get(
      f"https://api.agents.slng.ai/v1/agents/{agents[0]['id']}",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
  ).json()

  print(agent["template_variables"])
  # {"clinic_name": {"required": true, "default": "Downtown Health Clinic"}, ...}
  ```
</CodeGroup>

## Delete an agent

Returns `204 No Content` on success.

<CodeGroup>
  ```javascript JavaScript theme={null}
  await fetch(`https://api.agents.slng.ai/v1/agents/${agent.id}`, {
    method: "DELETE",
    headers: { Authorization: "Bearer SLNG_API_KEY" },
  });
  ```

  ```python Python theme={null}
  requests.delete(
      f"https://api.agents.slng.ai/v1/agents/{agent['id']}",
      headers={"Authorization": "Bearer SLNG_API_KEY"},
  )
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.agents.slng.ai/v1/agents/AGENT_ID \
    -H "Authorization: Bearer SLNG_API_KEY"
  ```
</CodeGroup>