Developer tools

The sipsandwich tenant API is the automation interface for SIP trunks, phone numbers, Retell workflows, call telemetry, and trace sessions. The public contract and interactive operations are in the API reference.

Install

The SDK, CLI, and MCP server are published on npm under the MIT license:

npm install @sipsandwichai/sdk
npm install --global @sipsandwichai/cli
npx -y @sipsandwichai/mcp

All three are generated from the same public API contract and share one version number. The carrier SIP header mapping operations described in Map carrier SIP headers to Retell require version 0.2.0 or later.

Authentication

Create a tenant API token in Settings → Security → API access. Keep the ss_api_... value in your secret manager and expose it to a local process only through an environment variable:

export SIPSANDWICH_API_TOKEN='ss_api_...'
export SIPSANDWICH_PHONE_NUMBER_ID='00000000-0000-0000-0000-000000000000'

All three tools use the public API origin, https://api.sipsandwich.ai, and send the token as Authorization: Bearer .... A token is tenant-scoped; it does not grant access to another workspace. Never put a token in a prompt, source file, screenshot, or command history.

The browser application at https://app.sipsandwich.ai uses its own session cookies. Use the API origin and a tenant token for SDK, CLI, MCP, and curl automation.

HTTP API

The HTTP API is available independently of the packages. For example, read a phone number's current inbound route:

curl --fail-with-body \
  "https://api.sipsandwich.ai/api/v1/phone-numbers/$SIPSANDWICH_PHONE_NUMBER_ID/inbound-destination" \
  -H "Authorization: Bearer $SIPSANDWICH_API_TOKEN"

Update the route with one of the three supported destination forms:

# Replace provider.example with your public SIP hostname or IPv4 endpoint.
curl --fail-with-body \
  -X PUT \
  "https://api.sipsandwich.ai/api/v1/phone-numbers/$SIPSANDWICH_PHONE_NUMBER_ID/inbound-destination" \
  -H "Authorization: Bearer $SIPSANDWICH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"mode":"sip_uri","uri":"sip:100@provider.example:5060;transport=tcp"}'

# Switch the number back to Retell.
curl --fail-with-body \
  -X PUT \
  "https://api.sipsandwich.ai/api/v1/phone-numbers/$SIPSANDWICH_PHONE_NUMBER_ID/inbound-destination" \
  -H "Authorization: Bearer $SIPSANDWICH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"mode":"retell"}'

The third form selects an enabled registration connection already in the same workspace:

{
  "mode": "sip_connection",
  "trunkId": "00000000-0000-0000-0000-000000000001",
  "user": "100"
}

A custom URI must use sip: or sips: with a user and a hostname or IPv4 address, and may include a port and udp, tcp, or tls transport. The API rejects credentials, URI headers, private or reserved addresses, IPv6-only DNS, and sipsandwich edge destinations. Saved connections are tenant-scoped and credentials are never returned. Updating a destination changes inbound SIP signaling only; it does not change provider registration or import/update a Retell number.

TypeScript and JavaScript SDK

The SDK provides a dependency-free SipSandwich client for Node.js 22+ and Fetch-compatible runtimes. Resource helpers cover Retell, SIP trunks, phone numbers, calls, and trace sessions. Every public OpenAPI operation is also available through the typed operations catalog, which is the current SDK surface for inbound destination routing:

import { SipSandwich } from "@sipsandwichai/sdk";

const phoneNumberId = process.env.SIPSANDWICH_PHONE_NUMBER_ID;
const apiToken = process.env.SIPSANDWICH_API_TOKEN;
if (!phoneNumberId || !apiToken) {
  throw new Error("SIPSANDWICH_PHONE_NUMBER_ID and SIPSANDWICH_API_TOKEN are required");
}

const client = new SipSandwich({ apiToken });

const current = await client.operations.getInboundDestination({
  id: phoneNumberId
});
console.log(current.destination, current.connections);

await client.operations.updateInboundDestination({
  id: phoneNumberId,
  body: {
    mode: "sip_uri",
    uri: "sip:100@provider.example:5060;transport=tcp"
  }
});

await client.operations.updateInboundDestination({
  id: phoneNumberId,
  body: { mode: "retell" }
});

The client defaults to https://api.sipsandwich.ai, a 60-second timeout, and retries safe GET requests for transient failures. Mutations are not retried unless retryMutations is enabled. The SDK exports typed OpenAPI components, operation IDs, and the generated contract; the source README has the complete resource and error-handling reference.

CLI

The CLI maps every public OpenAPI operationId to a flat kebab-case command. Provide the token through the environment or use the interactive login flow:

export SIPSANDWICH_API_TOKEN='ss_api_...'
sipsandwich auth whoami
sipsandwich get-inbound-destination "$SIPSANDWICH_PHONE_NUMBER_ID"

sipsandwich update-inbound-destination "$SIPSANDWICH_PHONE_NUMBER_ID" \
  --body '{"mode":"sip_uri","uri":"sip:100@provider.example:5060;transport=tcp"}'

sipsandwich update-inbound-destination "$SIPSANDWICH_PHONE_NUMBER_ID" \
  --body '{"mode":"retell"}'

sipsandwich auth login validates a token before storing it in a mode-0600 local config file. CI environment credentials take precedence over that saved file. JSON is the default output; --output jsonl and --output table are available for collection results. Request bodies can also come from a JSON file or stdin, and --dry-run prints a request with authorization redacted without sending it. Run sipsandwich --help for the generated command list.

MCP server

The MCP server exposes one validated tool per public API operation over stdio. Configure your MCP host to run it with the token in its environment:

{
  "mcpServers": {
    "sipsandwich": {
      "command": "npx",
      "args": ["-y", "@sipsandwichai/mcp"],
      "env": {
        "SIPSANDWICH_API_TOKEN": "ss_api_..."
      }
    }
  }
}

The generated routing tools are named sipsandwich_get_inbound_destination and sipsandwich_update_inbound_destination. The server also publishes the exact contract as the sipsandwich://openapi resource. Optional environment values are SIPSANDWICH_BASE_URL, SIPSANDWICH_TIMEOUT_MS, and SIPSANDWICH_MAX_RETRIES. Protocol data is written to stdout; PCAP downloads are returned as embedded binary MCP resources.

Choosing an option

Option	Best for	Get it
HTTP API	Any language, scripts, and integration tests	Available at `api.sipsandwich.ai`
TypeScript/JavaScript SDK	Typed Node.js or Fetch-compatible applications	`npm install @sipsandwichai/sdk`
CLI	Shell automation and human-readable JSON/table output	`npm install --global @sipsandwichai/cli`
MCP server	MCP-compatible assistants and IDE hosts	`npx -y @sipsandwichai/mcp`

For endpoint parameters, response schemas, and authentication requirements, use the API reference. For the browser setup flow, start with Getting started.

Install​

Authentication​

HTTP API​

TypeScript and JavaScript SDK​

CLI​

MCP server​

Choosing an option​