REST API - Layercode

Authorize Client Session

To connect a client (browser or mobile app) to a Layercode voice agent, you must first authorize the session. This is done by calling the Layercode REST API endpoint below from your backend. How the authorization flow works: When using a Layercode frontend SDK (such as @layercode/react-sdk or @layercode/js-sdk), the SDK will automatically make a POST request to the authorizeSessionEndpoint URL that you specify in your frontend code. This authorizeSessionEndpoint should be an endpoint on your own backend (not Layercode’s). Your backend receives this request from the frontend, then securely calls the Layercode REST API (https://api.layercode.com/v1/agents/web/authorize_session) using your LAYERCODE_API_KEY. Your backend then returns the client_session_key to the frontend.

Your Layercode API key should never be exposed to the frontend. Always call this endpoint from your backend, then return the client_session_key to your frontend.

Endpoint

POST https://api.layercode.com/v1/agents/web/authorize_session

Headers

string

required

Bearer token using your LAYERCODE_API_KEY.

string

default:"application/json"

required

Must be application/json.

Request Body

string

required

The ID of the Layercode agent the client should connect to.

string

(Optional) The conversation ID to resume an existing conversation. If not provided, a new conversation will be created.

object

(Optional) Per-session pipeline configuration override. When provided, it is stored on the session and takes precedence over the agent’s saved config for that session. Use this to customize the config options (e.g. the TTS voice).

Response

string

required

The key your frontend uses to connect to the Layercode WebSocket API.

string

required

The unique conversation ID.

object

Optional configuration for this session used by the frontend SDK. When present, it can include:
transcription.trigger and VAD settings such as vad.enabled, vad.gate_audio, vad.buffer_frames, vad.model, vad.positive_speech_threshold, vad.negative_speech_threshold, vad.redemption_frames, vad.min_speech_frames, vad.pre_speech_pad_frames, vad.frame_samples.

Example Request

# Example with only agent_id (creates a new session)
curl -X POST https://api.layercode.com/v1/agents/web/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag-123456"}'

# Example with agent_id and conversation_id (resumes an existing conversation)
curl -X POST https://api.layercode.com/v1/agents/web/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag-123456", "conversation_id": "lc_conv_abc123..."}'

# Example with per-session config
curl -X POST https://api.layercode.com/v1/agents/web/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag-123456",
    "config": {
      "type": "voice",
      "clients": {
        "browser": {
          "enabled": true
        }
      },
      "plugins": [
        { "use": "stt.deepgram", "options": { "model_id": "flux" } },
        { "use": "turn_manager", "options": { "mode": "automatic" } },
        { "use": "agent.llm", "options": { "provider": "google", "model_id": "gemini-2.5-flash-lite" } },
        { "use": "tts.rime", "options": { "model_id": "mistv2", "voice_id": "courtney" } }
      ],
      "session_webhook": {
        "url": "https://example.com/session-webhook",
        "events": ["session.start", "session.end", "session.update"],
        "custom_metadata": { "tenant_id": "t_42", "plan": "enterprise" },
        "custom_headers": { "x-tenant-id": "t_42", "x-session-origin": "mobile" }
      }
    }
  }'

Example Response

{
  "client_session_key": "lc_sesskey_abc123...",
  "conversation_id": "lc_conv_abc123..."
}

Error Responses

string

required

Error message describing the problem.

Possible error cases:

400 – Invalid or missing bearer token, invalid agent ID, missing or invalid conversation ID.
402 – Insufficient balance for the organization.

Example error response:

{
  "error": "insufficient balance"
}

Example: Backend Endpoint (Next.js)

Here’s how you might implement an authorization endpoint in your backend (Next.js example):

Next.js app/api/authorize/route.ts

export const dynamic = 'force-dynamic';
import { NextResponse } from 'next/server';

export const POST = async (request: Request) => {
  // Here you could do any user authorization checks you need for your app
  const endpoint = 'https://api.layercode.com/v1/agents/web/authorize_session';
  const apiKey = process.env.LAYERCODE_API_KEY;
  if (!apiKey) {
    throw new Error('LAYERCODE_API_KEY is not set.');
  }
  const requestBody = await request.json();
  if (!requestBody || !requestBody.agent_id) {
    throw new Error('Missing agent_id in request body.');
  }
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${apiKey}`
      },
      body: JSON.stringify(requestBody)
    });
    if (!response.ok) {
      const text = await response.text();
      throw new Error(text || response.statusText);
    }
    return NextResponse.json(await response.json());
  } catch (error: any) {
    console.log('Layercode authorize session response error:', error.message);
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
};

For other backend frameworks (Express, FastAPI, etc.), the logic is the same: receive a request from your frontend, call the Layercode authorize_session endpoint with your API key, and return the client_session_key to your frontend.

Agents

List Agents

GET https://api.layercode.com/v1/agents

string

required

Bearer token using your LAYERCODE_API_KEY.

Response

Returns all agents.

array

required

Each agent object includes id, name, type, agent_template_id, created_at, updated_at, and assigned_phone_numbers (array of phone number assignments with phone_number, twilio_sid, friendly_name, assigned_at).

Example

curl -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  https://api.layercode.com/v1/agents

{
  "agents": [
    {
      "id": "ag-123456",
      "name": "My Agent ag-123456",
      "type": "voice",
      "agent_template_id": "tmpl_default",
      "created_at": "2024-04-01T12:00:00.000Z",
      "updated_at": "2024-04-08T16:30:16.000Z",
      "assigned_phone_numbers": [
        {
          "phone_number": "+15551234567",
          "twilio_sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "friendly_name": "Support Line",
          "assigned_at": "2024-04-02T09:21:00.000Z"
        }
      ]
    }
  ]
}

Create Agent From Template

POST https://api.layercode.com/v1/agents

string

required

Bearer token using your LAYERCODE_API_KEY.

string

default:"application/json"

required

Must be application/json.

string

Optional template ID to initialize the agent configuration. If omitted, the default recommended template is used.

string

Optional display name for the new agent. If omitted, Layercode assigns a default name (e.g., My Agent ag-123456).

Response

Returns the newly created agent record, including configuration and webhook secret.

string

required

Unique identifier for the agent.

string

required

Human-friendly name assigned by Layercode.

string

required

Agent type (currently voice).

object

required

Full pipeline configuration cloned from the template.

string

required

Secret used to validate incoming webhooks.

string

required

ID of the template used to create the agent.

curl -X POST https://api.layercode.com/v1/agents \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tmpl_sales", "name": "Sales Assistant" }'

Get Agent Details

GET https://api.layercode.com/v1/agents/{agent_id}

string

required

Bearer token using your LAYERCODE_API_KEY.

Response

Returns the agent.

string

required

Agent ID.

string

required

Agent display name.

object

required

Current pipeline configuration.

array

Array of phone number assignments for this agent.

curl -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  https://api.layercode.com/v1/agents/ag-123456

Update Agent Configuration

POST https://api.layercode.com/v1/agents/{agent_id}

string

required

Bearer token using your LAYERCODE_API_KEY.

string

default:"application/json"

required

Must be application/json.

string

URL for production webhooks. When provided, agent.llm is swapped for agent.webhook (disabling demo_mode and routing traffic to your backend).

string

Optional display name to set for this agent. If omitted, the name remains unchanged.

string

Optional display name to set for this agent. If omitted, the name remains unchanged.

Response

Returns the updated agent record with the new configuration.

curl -X POST https://api.layercode.com/v1/agents/ag-123456 \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://example.com/layercode-webhook"
  }'

Sessions

Get Session Details

GET https://api.layercode.com/v1/agents/{agent_id}/sessions/{session_id}

string

required

Bearer token using your LAYERCODE_API_KEY.

Response

Returns JSON with details about the session, transcript, and recording status.

string

required

Connection ID for the session.

string

required

ID of the agent.

string

ISO timestamp when the connection started.

string

ISO timestamp when the connection ended (if ended).

number

Total connection duration in milliseconds.

object

Custom metadata associated with the session.

string

Caller phone number (Twilio), if applicable.

string

Caller country code (Twilio), if applicable.

string

Agent phone number (Twilio), if applicable.

string

Agent phone number country code (Twilio), if applicable.

string

IP address of the connection.

string

Country code derived from IP address when available.

number

Total seconds of user speech.

number

Total seconds of generated speech.

number

Processing latency in milliseconds.

array

Array of transcript entries. Each entry includes: timestamp, user_message, assistant_message, latency_ms.

string

One of not_available, in_progress, completed.

string

If recording_status is completed, a URL to download the WAV recording for this session connection.

Example

curl -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  https://api.layercode.com/v1/agents/ag-123456/sessions/lc_conn_abc123

Download Session Recording

GET https://api.layercode.com/v1/agents/{agent_id}/sessions/{session_id}/recording

string

required

Bearer token using your LAYERCODE_API_KEY.

Returns a WAV audio file if available.

curl -L -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -o session.wav \
  https://api.layercode.com/v1/agents/ag-123456/sessions/lc_conn_abc123/recording

Recordings are generated after a session completes. If a recording is still processing, the details endpoint will return recording_status: “in_progress”.

Once your frontend receives the client_session_key, it can connect to the Layercode WebSocket API to start streaming audio.

Calls

Initiate Outbound Call

POST https://api.layercode.com/v1/agents/ag-123456/calls/initiate_outbound

string

required

The phone number assigned to your Layercode Agent that will make the call.

Remember: the from_phone_number must be a number already assigned to your Laycode Agent in the dashboard.

string

required

The phone number to call (e.g., your mobile number for testing).

Response

string

required

The unique conversation ID.

A Session (associated with the returned conversation_id) will be created shortly after once Twilio initiates the call)

Example Request

  curl -X POST https://api.layercode.com/v1/agents/ag-123456/calls/initiate_outbound \
  -H 'Authorization: Bearer $LAYERCODE_API_KEY' \
  -H 'Content-Type: application/json' \
  -D '{
      "from_phone_number": "NUMBER_ASSIGNED_TO_YOUR_AGENT",
      "to_phone_number": "PHONE_NUMBER_TO_CALL"
  }'

Example Response

{
  "conversation_id": "lc_conv_abc123..."
}

Error Responses

string

required

Error message describing the problem.

Possible error cases:

400 – Invalid or missing bearer token, missing or request body, invalid from_phone_number (i.e. not assigned to the agent specified in the url).
429 – Account session concurrency limit reached.
402 – Insufficient balance for the organization.

Twilio Voice

TwiML Webhook

Use this endpoint as the Voice webhook in your Twilio phone number configuration. Layercode validates the incoming request, authorizes a session, and returns TwiML that connects the call to your agent’s WebSocket stream.

POST https://api.layercode.com/v1/agents/twilio/twiml

string

Signature supplied by Twilio for request verification. Required when you have stored Twilio credentials in Layercode.

string

required

Call direction reported by Twilio (e.g., inbound or outbound-api).

string

required

Caller phone number.

string

Caller country code supplied by Twilio.

string

required

Phone number assigned to your agent.

string

Destination country code supplied by Twilio.

Response

Returns TwiML that streams the call to the Layercode Twilio WebSocket endpoint.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://twilio.layercode.com/v1/agents/twilio/websocket/{client_session_key}" />
  </Connect>
</Response>

The response Streaming URL is generated dynamically for each request. Do not cache or reuse the client session key.

​Authorize Client Session

​Endpoint

​Headers

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Example: Backend Endpoint (Next.js)

​Agents

​List Agents

​Response

​Example

​Create Agent From Template

​Response

​Get Agent Details

​Response

​Update Agent Configuration

​Response

​Sessions

​Get Session Details

​Response

​Example

​Download Session Recording

​Calls

​Initiate Outbound Call

​Response

​Example Request

​Example Response

​Error Responses

​Twilio Voice

​TwiML Webhook

​Response

Authorize Client Session

Endpoint

Headers

Request Body

Response

Example Request

Example Response

Error Responses

Example: Backend Endpoint (Next.js)

Agents

List Agents

Response

Example

Create Agent From Template

Response

Get Agent Details

Response

Update Agent Configuration

Response

Sessions

Get Session Details

Response

Example

Download Session Recording

Calls

Initiate Outbound Call

Response

Example Request

Example Response

Error Responses

Twilio Voice

TwiML Webhook

Response