Skip to content

docs: add purpose and usage descriptions to REST operations #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Devon-White wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: add purpose and usage descriptions to REST operations #630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e83a4ce
docs: improve API operation descriptions
Devon-White Aug 24, 2026
6022684
docs: describe calling command schemas
Devon-White Aug 24, 2026
30c4b9f
docs: update .gitignore to include .superdesign directory
Devon-White Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,5 @@ dist

# Internal process artifacts (superpowers / brainstorming specs)
docs/superpowers/
.superpowers/
.superpowers/
.superdesign/
192 changes: 97 additions & 95 deletions fern/apis/compatibility/openapi.yaml
View file
Open in desktop

Large diffs are not rendered by default.

750 changes: 450 additions & 300 deletions fern/apis/signalwire-rest/openapi.yaml
View file
Open in desktop

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions specs/compatibility-api/accounts/main.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ namespace CompatibilityAPI.Accounts {
@operationId("list_accounts")
@summary("List Accounts")
@doc("""
This endpoint will return a list that contains Project you are connecting as and any subprojects.
Lists the project used to authenticate the request and its subprojects as Account resources. Use it when an integration identifies SignalWire projects by Account SID. For JSON project-management operations, use [List projects](/docs/apis/rest/projects/list-projects).

${tokenPermissions<"_Management_">}
""")
Expand Down Expand Up @@ -54,7 +54,7 @@ namespace CompatibilityAPI.Accounts {
@operationId("create_subprojects")
@summary("Create Subprojects")
@doc("""
This endpoint creates a subproject on the Project you are connecting as.
Creates a subproject beneath the project used to authenticate the request and returns it as an Account. Use this route for integrations built around Account SIDs and form-encoded requests; use [Create a subproject](/docs/apis/rest/projects/create-subproject) for a JSON request.

${tokenPermissions<"_Management_">}
""")
Expand All @@ -71,7 +71,7 @@ namespace CompatibilityAPI.Accounts {
@operationId("get_account")
@summary("Find an Account by ID")
@doc("""
Find a Project (also referred to as _Account_) by ID.
Retrieves one project as an Account by SID. Use it when an integration identifies projects with Account SIDs; use [Retrieve a project](/docs/apis/rest/projects/get-project) for the SignalWire REST representation.

${tokenPermissions<"_Management_">}
""")
Expand All @@ -84,7 +84,7 @@ namespace CompatibilityAPI.Accounts {
@operationId("update_account")
@summary("Update an Account")
@doc("""
Update a Project (also referred to as _Account_).
Renames a project through its Account resource. `FriendlyName` is required and is the only attribute this operation can change; account status cannot be changed here. Use [Update a project](/docs/apis/rest/projects/update-project) for JSON requests and project security settings.

${tokenPermissions<"_Management_">}
""")
Expand Down
10 changes: 5 additions & 5 deletions specs/compatibility-api/applications/main.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ namespace CompatibilityAPI.Applications {
@operationId("list_applications")
@summary("List Applications")
@doc("""
The ability to read all of the applications that are associated with your Account. This will be returned as a list of applications.
Lists the account's Applications, which provide reusable voice and messaging routing. These applications are also available as addressable [cXML Applications](/docs/apis/rest/cxml-applications/list-cxml-applications) in the SignalWire REST API. Use this collection for code built around Application SIDs.

${tokenPermissions<"_Voice_ or _Messaging_ or _Fax_">}
""")
Expand Down Expand Up @@ -56,7 +56,7 @@ namespace CompatibilityAPI.Applications {
@operationId("create_application")
@summary("Create an Application")
@doc("""
Create an Application.
Creates a reusable voice and messaging routing application in the account. The new Application also becomes an addressable [cXML Application](/docs/apis/rest/cxml-applications/list-cxml-applications). The cXML Applications API manages existing applications but does not create them, so create Applications here.

${tokenPermissions<"_Voice_ or _Messaging_ or _Fax_">}
""")
Expand All @@ -74,7 +74,7 @@ namespace CompatibilityAPI.Applications {
@operationId("get_application")
@summary("Find an Application by ID")
@doc("""
Find an Application by ID.
Retrieves one Application by SID so you can inspect its reusable voice and messaging routing. The application can also be read with [Get cXML application](/docs/apis/rest/cxml-applications/get-cxml-application), which addresses it by resource ID rather than SID.

${tokenPermissions<"_Voice_ or _Messaging_ or _Fax_">}
""")
Expand All @@ -88,7 +88,7 @@ namespace CompatibilityAPI.Applications {
@operationId("update_application")
@summary("Update an Application")
@doc("""
Update an Application.
Changes how an Application routes voice and messaging requests or status callbacks while preserving its SID. The change is also visible through [Update cXML application](/docs/apis/rest/cxml-applications/update-cxml-application), because both operations manage the same application.

${tokenPermissions<"_Voice_ or _Messaging_ or _Fax_">}
""")
Expand All @@ -109,7 +109,7 @@ namespace CompatibilityAPI.Applications {
@operationId("delete_application")
@summary("Delete an Application")
@doc("""
Delete an Application.
Deletes an Application by SID. This also removes its [cXML Application](/docs/apis/rest/cxml-applications/list-cxml-applications) representation and resource addresses, and clears the Application from phone numbers that route through it. Server-backed [cXML Webhooks](/docs/apis/rest/cxml-webhook/list-cxml-webhooks) are separate resources and are not affected.

${tokenPermissions<"_Voice_ or _Messaging_ or _Fax_">}
""")
Expand Down
36 changes: 18 additions & 18 deletions specs/compatibility-api/available-phone-numbers/main.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
@operationId("list_available_phone_number_resources")
@summary("List of AvailablePhoneNumber resources")
@doc("""
Returns a list of URIs to phone number resources available to the account, categorized by type (Local, Toll-Free, Mobile, etc) and ISO country.
Returns the resource directories for searching available numbers, grouped by ISO country and number type such as Local or Toll-Free. This operation lists search routes rather than purchasable numbers; use a country-specific search below or SignalWire REST [Search phone numbers](/docs/apis/rest/phone-numbers/search-available-phone-numbers) to query inventory.

${tokenPermissions<"_Numbers_">}
""")
Expand All @@ -28,7 +28,7 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
@operationId("list_available_phone_number_resources_by_country")
@summary("List of AvailablePhoneNumber resources by country")
@doc("""
Returns a list of URIs to phone number resources available to the account in the specified ISO country, categorized by type (Local, Toll-Free, Mobile, etc).
Returns the available-number search directories for one ISO country, grouped by number type such as Local or Toll-Free. This operation describes search routes; use [Search local available phone numbers](/docs/compatibility-api/rest/available-phone-numbers/search-local-available-phone-numbers) or the toll-free search to return actual inventory.

${tokenPermissions<"_Numbers_">}
""")
Expand All @@ -41,7 +41,7 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
@operationId("search_local_available_phone_numbers")
@summary("Search for available phone numbers that match your criteria.")
@doc("""
Search for Local AvailablePhoneNumbers.
Searches SignalWire inventory for local phone numbers available in one ISO country. Results are candidates, not project resources, until purchased through Incoming Phone Numbers or the native purchase operation. Use the [toll-free search](/docs/compatibility-api/rest/available-phone-numbers/search-toll-free-available-phone-numbers) for toll-free inventory, or native [Search phone numbers](/docs/apis/rest/phone-numbers/search-available-phone-numbers) for the JSON API.

${tokenPermissions<"_Numbers_">}
""")
Expand All @@ -66,22 +66,22 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
Contains?: string,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeAllAddressRequired?: boolean,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeForeignAddressRequired?: boolean,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeLocalAddressRequired?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
FaxEnabled?: boolean,

Expand All @@ -96,17 +96,17 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
InRegion?: string,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
MmsEnabled?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
SmsEnabled?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
VoiceEnabled?: boolean,
):
Expand All @@ -118,7 +118,7 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
@operationId("search_toll_free_available_phone_numbers")
@summary("Find toll-free numbers")
@doc("""
Search for toll-free AvailablePhoneNumbers.
Searches SignalWire inventory for toll-free phone numbers available in one ISO country. Results are candidates, not project resources, until purchased through Incoming Phone Numbers or the native purchase operation. Use the [local search](/docs/compatibility-api/rest/available-phone-numbers/search-local-available-phone-numbers) for local inventory, or native [Search phone numbers](/docs/apis/rest/phone-numbers/search-available-phone-numbers) for the JSON API.

${tokenPermissions<"_Numbers_">}
""")
Expand All @@ -143,22 +143,22 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
Contains?: string,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeAllAddressRequired?: boolean,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeForeignAddressRequired?: boolean,

@query
@doc("Accepted for Twilio compatibility but has no effect on the response.")
@doc("Accepted but has no effect on the response.")
@example(false)
ExcludeLocalAddressRequired?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
FaxEnabled?: boolean,

Expand All @@ -173,17 +173,17 @@ namespace CompatibilityAPI.AvailablePhoneNumbers {
InRegion?: string,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
MmsEnabled?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
SmsEnabled?: boolean,

@query
@doc("Not supported. Accepted for Twilio API compatibility.")
@doc("Accepted but not supported; has no effect on the response.")
@example(true)
VoiceEnabled?: boolean,
):
Expand Down
4 changes: 2 additions & 2 deletions specs/compatibility-api/available-phone-numbers/models/core.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ model AvailablePhoneNumber {
@doc("Whether or not a number can receive calls and messages.")
capabilities: PhoneNumberCapabilities;

@doc("Always `false`. Included for Twilio API compatibility.")
@doc("Always `false`. Retained for response-shape compatibility.")
@example(false)
beta: boolean;
}
Expand Down Expand Up @@ -104,7 +104,7 @@ model CountryResource {
@example("/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/AvailablePhoneNumbers/US")
uri: string;

@doc("Always `false`. Included for Twilio API compatibility.")
@doc("Always `false`. Retained for response-shape compatibility.")
@example(false)
beta: boolean;

Expand Down
18 changes: 9 additions & 9 deletions specs/compatibility-api/calls/main.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ namespace CompatibilityAPI.Calls {
@operationId("list_all_calls")
@summary("List all Calls")
@doc("""
List all calls.
Lists the account's calls. Each call has a Call SID that cXML integrations can use for inspection or control. Use [Retrieve a Call](/docs/compatibility-api/rest/calls/retrieve-a-call) when you already have its SID; use the [Calling API](/docs/apis/rest/calls/call-commands) for SWML-driven call commands.

${tokenPermissions<"_Voice_">}
""")
Expand Down Expand Up @@ -109,7 +109,7 @@ namespace CompatibilityAPI.Calls {
@operationId("create_a_call")
@summary("Create a Call")
@doc("""
Create a call.
Starts an outbound call whose behavior is supplied by a cXML URL or Application SID. Use this form-encoded route for integrations built around cXML call control and Call SIDs; use the [Calling API](/docs/apis/rest/calls/call-commands) for SWML-driven calls and command-based control.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -127,7 +127,7 @@ namespace CompatibilityAPI.Calls {
@operationId("retrieve_a_call")
@summary("Retrieve a Call")
@doc("""
Retrieve a call.
Retrieves one call by SID so you can inspect a known call's progress and outcome. Use [List all Calls](/docs/compatibility-api/rest/calls/list-all-calls) to discover SIDs. The Calling API is command-oriented and uses its own call identifiers.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -141,7 +141,7 @@ namespace CompatibilityAPI.Calls {
@operationId("update_a_call")
@summary("Update a Call")
@doc("""
Update a call.
Redirects an active call to new cXML instructions, cancels a queued call, or completes an in-progress call. Use it when controlling a call by Call SID and form-encoded cXML settings; use the [Calling API](/docs/apis/rest/calls/call-commands) for SWML call commands.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -163,7 +163,7 @@ namespace CompatibilityAPI.Calls {
@operationId("delete_a_call")
@summary("Delete a Call")
@doc("""
Delete a call record from your account. If the delete is successful, a 204 response, with no body, will be returned.
Deletes a call record from the account and returns no body on success. This removes the record; it does not hang up an active call. Use [Update a Call](/docs/compatibility-api/rest/calls/update-a-call) with an appropriate status to cancel or complete a live call.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -184,7 +184,7 @@ namespace CompatibilityAPI.Calls {
@operationId("create_recording")
@summary("Create a Recording")
@doc("""
Create a recording.
Starts a recording resource for an active call. Use [Update a Recording](/docs/compatibility-api/rest/recordings/update-recording) to pause, resume, or stop it; use the account-level [Recordings](/docs/compatibility-api/rest/recordings/list-recordings) collection to find saved media across calls.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -205,7 +205,7 @@ namespace CompatibilityAPI.Calls {
@operationId("update_recording")
@summary("Update a Recording")
@doc("""
Pause, resume or stop a Recording. You can control what happens while recording is paused (replace pause with silence or skip it).
Pauses, resumes, or stops a recording on an active call. When pausing, choose whether the elapsed interval becomes silence in the media or is skipped. This controls an in-progress recording; account-level [Recordings](/docs/compatibility-api/rest/recordings/list-recordings) operations retrieve or delete saved media.

${tokenPermissions<"_Voice_">}
""")
Expand Down Expand Up @@ -233,7 +233,7 @@ namespace CompatibilityAPI.Calls {
@operationId("create_stream")
@summary("Create a Stream")
@doc("""
Create a stream.
Starts sending selected audio tracks from an active call to a secure WebSocket endpoint. Use it for live call-audio processing; use [Conference Streams](/docs/compatibility-api/rest/conference-streams/create-conference-stream) for an entire voice conference or [Video Room Streams](/docs/apis/rest/video/streams/list-room-streams) for RTMP video broadcasts.

${tokenPermissions<"_Voice_">}
""")
Expand All @@ -254,7 +254,7 @@ namespace CompatibilityAPI.Calls {
@operationId("update_stream")
@summary("Stop a Stream")
@doc("""
Stop a Stream.
Stops an active WebSocket audio stream on a call by stream SID. This ends media delivery without ending the call. Conference audio streams and Video RTMP streams have separate operations.

${tokenPermissions<"_Voice_">}
""")
Expand Down
Loading
Loading