REST Client | SignalWire

The REST namespace provides a synchronous 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 Python.

Example

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

from signalwire.rest import RestClient, SignalWireRestError
client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)
# Search for available numbers in area code 512
available = client.phone_numbers.search(areacode="512", max_results=3)
for number in available.get("data", []):
    print(f"{number['number']} - {number.get('region')}")
# Purchase the first available number
purchased = client.phone_numbers.create(number=available["data"][0]["number"])
print(f"Purchased: {purchased['number']}")
# List your AI agent resources
response = client.fabric.ai_agents.list()
for agent in response.get("data", []):
    print(f"Agent: {agent['name']} ({agent['id']})")
# Query recent voice call logs
logs = client.logs.voice.list(page_size=5)
for log in logs.get("data", []):
    print(f"Call from {log.get('from')} to {log.get('to')}")

All three constructor arguments can also be provided via environment variables: SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, and SIGNALWIRE_SPACE. When those are set, you can instantiate with RestClient() and no arguments.

Pagination

list() returns one page, the server’s first response. To walk every item across all pages, call paginate() on the same resource. It follows the response’s links.next until the last page. Most list resources have it; the few that don’t return a single page only.

for number in client.phone_numbers.paginate():
    print(number["number"])

Timeouts and retries

Pass a RequestOptions to the constructor to set a default timeout and retry policy for every request, or to any method’s request_options= argument to override it for one call.

Error Handling

REST errors raise SignalWireRestError. A request that never reaches the server (connection refused, DNS failure, timeout) raises SignalWireRestTransportError, a subclass whose status_code is None, so one except clause covers both. The error carries the response headers and the platform request_id for support correlation.

from signalwire.rest import RestClient, SignalWireRestError
client = RestClient()
try:
    client.phone_numbers.get("nonexistent-id")
except SignalWireRestError as e:
    print(f"HTTP {e.status_code}: {e.body}")
    print(f"URL: {e.method} {e.url}")
    print(f"Request ID: {e.request_id}")

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 sent message bodies.

Projects

Create and manage subprojects and rotate signing keys.

MFA

Multi-factor authentication via SMS and voice.