REST Client | SignalWire

The REST namespace provides an HTTP client for the SignalWire platform APIs. It organizes every HTTP endpoint into namespaced resource objects with standard CRUD operations, letting you manage phone numbers, fabric resources, call logs, video rooms, datasphere documents, and more from TypeScript.

Example

Search for available phone numbers, purchase one, and assign it to a fabric AI agent resource:

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
// Search for available numbers in area code 512
const available = await client.phoneNumbers.search({ areacode: "512", max_results: 3 });
for (const number of available.data ?? []) {
  console.log(`${number.number} - ${number.region}`);
}
// Purchase the first available number
const purchased = await client.phoneNumbers.create({ number: available.data[0].number });
console.log(`Purchased: ${purchased.number}`);
// List your AI agent resources
const response = await client.fabric.aiAgents.list();
for (const agent of response.data ?? []) {
  console.log(`Agent: ${agent.display_name} (${agent.id})`);
}
// Query recent voice call logs
const logs = await client.logs.voice.list({ page_size: 5 });
for (const log of logs.data ?? []) {
  if ('from' in log) {
    console.log(`Call from ${log.from} to ${log.to}`);
  }
}

All three constructor arguments can also be provided via environment variables: SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, and SIGNALWIRE_SPACE (or SIGNALWIRE_REST_BASE_URL for a full base URL, which takes precedence). When those are set, you can instantiate with new RestClient() and no arguments.

Pagination

list() returns one page. paginate() returns an async iterator that follows the server’s next-page links and yields one item at a time, so you don’t build the page loop yourself. Query parameters apply to the first request only.

import { RestClient } from "@signalwire/sdk";
const client = new RestClient();
for await (const address of client.fabric.addresses.paginate()) {
  console.log(address.name);
}

Timeouts, retries, and cancellation

Every resource method accepts a trailing requestOptions object that sets the timeout, retry count, backoff, and an AbortSignal for that one call. Pass the same object to the constructor to set a client-wide default. See RequestOptions.

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({ requestOptions: { timeout: 10, retries: 2 } });
const controller = new AbortController();
const numbers = await client.phoneNumbers.list(
  undefined,
  { abortSignal: controller.signal },
);

Error handling

REST errors throw RestError. A request that never reaches the server, such as a DNS failure or a timeout, throws RestTransportError, a subclass of RestError with a null status code, so one catch handles both:

import { RestClient, RestError } from "@signalwire/sdk";
const client = new RestClient();
try {
  await client.phoneNumbers.get("nonexistent-id");
} catch (e) {
  if (e instanceof RestError) {
    console.log(`HTTP ${e.statusCode}: ${e.body}`);
    console.log(`URL: ${e.method} ${e.url}`);
    console.log(`Request ID: ${e.requestId}`);
  }
}

Resources

RestClient

Constructor, authentication, and all namespace properties.

Phone Numbers

Search, purchase, and manage phone numbers.

Fabric

AI agents, SWML scripts, subscribers, call flows, and tokens.

Calling

REST-based call control with 37+ commands.

Video

Rooms, conferences, sessions, recordings, and streams.

Datasphere

Document management and semantic search.

Logs

Message, voice, fax, and conference log queries.

Registry

10DLC brand and campaign registration.

Messages

Send SMS and MMS messages and redact message bodies.

Projects

Create and manage projects and rotate signing keys.

MFA

Multi-factor authentication via SMS and voice.