You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: fern/products/apis/pages/core/base-url.mdx
+30-4Lines changed: 30 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,38 @@ title: Base URL
4
4
slug: /base-url
5
5
---
6
6
7
-
Each Space on SignalWire gets its own subdomain and each Space will have its own URLs for accessing the REST API.
7
+
Every Space on SignalWire has its own subdomain, and every API request goes through your Space's subdomain over HTTPS. Plain HTTP requests are rejected.
8
8
9
-
All calls in the provided examples use the `demo` subdomain; however, please note that the **actual base URL** you will use will differ for each Space, since it will be customized to include your unique Space name.
9
+
```shell
10
+
https://{your_space}.signalwire.com
11
+
```
12
+
13
+
Throughout these docs, examples use the placeholder `example.signalwire.com` — replace `example` with your own Space's subdomain when copying requests into your code.
14
+
15
+
## Find your subdomain
16
+
17
+
Your Space subdomain is the prefix that comes before `.signalwire.com` in your Dashboard URL. If you sign in at `https://acme.signalwire.com/dashboard`, your subdomain is `acme`.
18
+
19
+
You'll also find it under **API Credentials** in the [SignalWire Dashboard](https://my.signalwire.com?page=credentials), alongside your Project ID and API tokens.
20
+
21
+
## URL structure
10
22
11
-
For your own custom URL, replace `demo` with your unique subdomain.
All SignalWire REST APIs require HTTPS. Requests sent over plain HTTP are refused — there is no automatic upgrade. Make sure your HTTP client is configured for TLS.
Copy file name to clipboardExpand all lines: fern/products/apis/pages/core/error-codes.mdx
+55-1Lines changed: 55 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,61 @@ slug: /error-codes
5
5
max-toc-depth: 3
6
6
---
7
7
8
-
When using SignalWire REST APIs, some errors will include error codes. Below, you will find a list of our unique error codes and a short explanation of each to help with error handling and troubleshooting.
8
+
When a SignalWire REST request fails, the response combines a standard HTTP status code with a structured error body. This page covers the status codes you'll encounter, the shape of the error body, and a reference of the specific error codes returned in the body.
9
+
10
+
## HTTP status codes
11
+
12
+
SignalWire uses conventional HTTP status codes to signal the outcome of every request.
|`2xx`| Success — the request was accepted and processed. |
17
+
|`4xx`| Client error — the request was malformed, unauthorized, forbidden, missing, or rejected by validation. Don't retry without fixing the cause. |
18
+
|`5xx`| Server error — something went wrong on SignalWire's side. Safe to retry with backoff. |
19
+
20
+
The most common codes you'll see:
21
+
22
+
-`400 Bad Request` — the request was malformed (bad JSON, missing required fields).
23
+
-`401 Unauthorized` — credentials missing or invalid. See [Authorization](/docs/apis/authorization).
24
+
-`403 Forbidden` — your token lacks the required scope.
25
+
-`404 Not Found` — the resource doesn't exist, or doesn't belong to your project.
26
+
-`422 Unprocessable Entity` — the request was well-formed but failed validation. The body contains an [`errors` array](#error-response-body) with specifics.
27
+
-`429 Too Many Requests` — you've exceeded a rate limit. Back off and retry.
28
+
-`500 Internal Server Error` — an unexpected server-side failure. Retry with backoff; contact support if it persists.
29
+
30
+
## Error response body
31
+
32
+
Most endpoints under `/api/*` (including `/api/messaging`, `/api/calling`, `/api/fabric`, and others) return validation errors using this shape:
|`type`| The category of the error (e.g., `validation_error`). |
51
+
|`code`| A specific, machine-readable code — match this against the [reference below](#account_limit_exceeded) to map error codes to causes. |
52
+
|`message`| A human-readable description of what went wrong. |
53
+
|`attribute`| The request parameter that triggered the error, when applicable. |
54
+
|`url`| A link back to this documentation. |
55
+
56
+
A single response may contain multiple entries in `errors` if several fields failed validation at once. Always iterate the array rather than reading only the first entry.
57
+
58
+
Endpoints under `/api/relay/rest` use a slightly different shape: `{ errors: [{ detail, status, title, code }] }`. The `code` field still maps to the reference below.
59
+
60
+
## Error code reference
61
+
62
+
The `code` field above maps to one of the values below. Each entry describes the specific condition that produced the error.
Copy file name to clipboardExpand all lines: fern/products/apis/pages/core/overview.mdx
+47-7Lines changed: 47 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,16 +4,56 @@ title: Overview
4
4
slug: /
5
5
---
6
6
7
-
Welcome to SignalWire's REST API. Our REST API is a set of endpoints that make interacting with SignalWire simple and familiar.
7
+
Welcome to the SignalWire REST API. Every capability on the platform — placing calls, sending messages, managing phone numbers, running video rooms, building AI agents — is reachable through a consistent set of HTTP endpoints under your Space's subdomain.
8
8
9
-
The REST API is structured like most other [REST](https://en.wikipedia.org/wiki/REST)APIs: we use predictable and clear resource-oriented URLs that utilize built-in HTTP features like authentication, verbs, and error codes. This enables you to easily use any HTTP client in any language to make requests.
9
+
Requests and responses are JSON over HTTPS, authenticated with your Project ID and API token. Endpoints follow standard [REST](https://en.wikipedia.org/wiki/REST)conventions: predictable resource URLs, conventional HTTP verbs, and structured status codes for every outcome — including errors.
10
10
11
-
Proper HTTP status codes and [JSON](https://www.json.org/json-en.html) are returned in all REST API endpoints, including errors.
HTTP status codes, the structured error response shape, and a full reference of error code values.
30
+
</Card>
17
31
</CardGroup>
18
32
33
+
## Use the REST API from your code
34
+
35
+
The SignalWire [Server SDKs](/docs/server-sdks) wrap every REST endpoint in idiomatic, type-safe client libraries — use them in production code instead of crafting HTTP requests by hand. Each SDK exposes the full REST surface (phone numbers, calling, messaging, video, fabric resources, and more) through namespaced resource objects with standard CRUD operations. Pick the language that matches your stack from the [Server SDKs overview](/docs/server-sdks).
36
+
37
+
## Try it in Postman
38
+
39
+
For developers who prefer working in Postman, we maintain an official collection that mirrors every REST endpoint with pre-built requests, example payloads, and a configurable environment for your SignalWire credentials. It's a fully supported alternative to the API playground built into these docs.
40
+
41
+
<Steps>
42
+
43
+
### Open the collection in Postman
44
+
45
+
Click **Run in Postman** to fork the collection into your own Postman workspace.
46
+
47
+
[<imgsrc="https://run.pstmn.io/button.svg"alt="Run In Postman"style={{ width: "128px", height: "32px" }} />](https://god.gw.postman.com/run-collection/16445495-86c9916b-baa8-4bb3-b62d-d4ae86b12d61?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D16445495-86c9916b-baa8-4bb3-b62d-d4ae86b12d61%26entityType%3Dcollection%26workspaceId%3D4f34e511-485e-4462-a432-20fbc2d1db33)
48
+
49
+
### Set your environment variables
50
+
51
+
Open the collection's **Variables** tab and fill in `space`, `project_id`, and `auth_token` from the [API pane](https://my.signalwire.com?page=credentials) of your SignalWire Dashboard.
52
+
53
+
### Send your first request
54
+
55
+
Open any endpoint — try **Phone Numbers** to list the numbers on your project, or **Messages** to fire off a test SMS — and hit **Send**. The collection uses your environment variables automatically.
56
+
57
+
</Steps>
58
+
19
59
Be sure to subscribe to the [SignalWire Community](https://signalwire.community) for information on new features and changes to the API and language libraries.
For developers who prefer working in Postman, we maintain an official Compatibility API collection with pre-built requests for every cXML endpoint, example payloads, and a configurable environment for your SignalWire credentials. It's a fully supported alternative to the API playground built into these docs — useful if Postman is already part of your workflow.
22
+
23
+
<Steps>
24
+
25
+
### Open the collection in Postman
26
+
27
+
Click **Run in Postman** to fork the collection into your own Postman workspace.
28
+
29
+
[<imgsrc="https://run.pstmn.io/button.svg"alt="Run In Postman"style={{ width: "128px", height: "32px" }} />](https://god.gw.postman.com/run-collection/16445495-16e14ee0-3762-42ac-9f4d-a61401e05209?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D16445495-16e14ee0-3762-42ac-9f4d-a61401e05209%26entityType%3Dcollection%26workspaceId%3D4f34e511-485e-4462-a432-20fbc2d1db33)
30
+
31
+
### Set your environment variables
32
+
33
+
Open the collection's **Variables** tab and fill in your Space subdomain, **AccountSid** (your Project ID — see [AccountSid vs ProjectID](#accountsid-vs-projectid) below), and **Auth Token** from the [API pane](https://my.signalwire.com?page=credentials) of your SignalWire Dashboard.
34
+
35
+
### Send your first request
36
+
37
+
Open any endpoint — try **Calls** to list the calls on your project, or **Messages** to send a test SMS — and hit **Send**. The collection uses your environment variables automatically.
0 commit comments