From 53fcdcc4c9d6a0955906c13aebd3bb13da31edfa Mon Sep 17 00:00:00 2001 From: August Date: Fri, 4 Sep 2026 16:38:41 +0000 Subject: [PATCH 1/3] docs(platform): add Projects page to `platform/core/`, with subproject detail --- .../platform/pages/platform/core/projects.mdx | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 fern/products/platform/pages/platform/core/projects.mdx diff --git a/fern/products/platform/pages/platform/core/projects.mdx b/fern/products/platform/pages/platform/core/projects.mdx new file mode 100644 index 0000000000..8f6f173e53 --- /dev/null +++ b/fern/products/platform/pages/platform/core/projects.mdx @@ -0,0 +1,99 @@ +--- +title: Projects +description: Projects group the phone numbers, resources, and credentials in your Space, and subprojects nest one level beneath a root project with their own Project ID and resources. +slug: /projects +max-toc-depth: 3 +--- + +A project is the container for what you build in a SignalWire Space. +Phone numbers, [resources](/docs/platform/resources), and +[API credentials](/docs/platform/your-signalwire-api-space) all belong to exactly one project, +which is how you group work by customer, by environment, or by any other classification you like. + +Your Space starts with one project, created alongside the Space itself, and you can add more +from your Dashboard at any time. + +## What a project scopes + +Each project carries its own Project ID and its own API tokens, and every request you make is +authenticated as one project and acts on that project alone. + +Security settings are per-project too. +Each project has its own [media URL protection](/docs/platform/media-protection) settings for +recordings, message media, and fax media, and its own choice of whether webhooks and callbacks +must use HTTPS. + +Not everything divides along project lines. +Voice and messaging [rate limits](/docs/platform/rate-limits) are account-level, counted across +every project in your Space. + +## Subprojects + +A subproject is a project nested one level beneath a root project. +It is a full project with its own Project ID and resources, but a subproject cannot contain other +subprojects. + +Unlike root projects, subprojects can be created and deleted through the +[Projects API](/docs/apis/rest/projects/list-projects), so an application can open and retire a +project per customer, per tenant, or per environment on its own. +Root projects are created in the Dashboard and can't be deleted through the API. + +### Create a subproject + +Authenticate as the root project and send the subproject's name, along with any security settings +you want it to start with. +A subproject cannot create another subproject, so a request authenticated as a subproject fails +with `422 nested_subprojects_not_allowed`. + + + +The response is the only place the new project's `signing_key` appears — it can't be retrieved +afterward, so capture it here. + + + +To get credentials for the new subproject, call +[Create API token](/docs/apis/rest/project-tokens/create-token) from the root project with the +subproject's ID in `subproject_id`. + +### Delete a subproject + +Only subprojects can be deleted through the API; targeting the root project returns +`422 only_subprojects_can_be_deleted`. + + + +A project must have no phone numbers before it can be deleted, or the request returns +`422 phone_numbers_must_be_removed`. +Deleting a subproject also migrates its registry brands and campaigns up to the parent project. + + + + + +## Manage projects through the API + +Every Projects API request reaches only the authenticated project and the subprojects beneath it. +[List projects](/docs/apis/rest/projects/list-projects) returns the authenticated project +alongside its subprojects, and each entry reports whether it is a subproject and which project it +belongs to. +A project ID outside that tree returns `404 Not Found`. + +[Update a project](/docs/apis/rest/projects/update-project) changes the name and security settings +of any project in that tree, root project included. + +Integrations built around Compatibility API Account SIDs see the same tree as Accounts: +[Create Subprojects](/docs/compatibility-api/rest/accounts/create-subprojects) and +[List accounts](/docs/compatibility-api/rest/accounts/list-accounts) cover the same ground with +form-encoded requests. + +## Next steps + + + + Every operation for listing, creating, updating, and deleting projects. + + + Find a project's Project ID and Space URL, and issue API tokens. + + From e33acbef3015f7de62c3116ac96f48f0c149b6a7 Mon Sep 17 00:00:00 2001 From: August Date: Fri, 4 Sep 2026 16:38:50 +0000 Subject: [PATCH 2/3] docs(platform): link projects and subprojects from signup, getting started, and credentials --- fern/products/platform/pages/getting-started.mdx | 14 ++++++++++++++ .../pages/platform/setup/api-credentials.mdx | 3 +++ .../pages/platform/setup/create-an-account.mdx | 12 +++++++++++- 3 files changed, 28 insertions(+), 1 deletion(-) diff --git a/fern/products/platform/pages/getting-started.mdx b/fern/products/platform/pages/getting-started.mdx index adf97ea380..47ade5aca3 100644 --- a/fern/products/platform/pages/getting-started.mdx +++ b/fern/products/platform/pages/getting-started.mdx @@ -272,6 +272,20 @@ const client = RestClient(PROJECT_ID, API_TOKEN, { ## Core concepts +### Projects and subprojects + +A **Project** groups everything you build: phone numbers, resources, and API credentials. +Every Space starts with one, and you can add more at any time. + +Beneath a Project you can nest **Subprojects**, one level deep. +A Subproject is a full project with its own Project ID, API tokens, and resources, which makes it +the way to isolate a customer, a tenant, or a staging environment. +Unlike root Projects, Subprojects can be created and deleted through the API. + + + What a project scopes, and how subprojects nest beneath one + + ### Communication channels SignalWire supports the following communication channels: diff --git a/fern/products/platform/pages/platform/setup/api-credentials.mdx b/fern/products/platform/pages/platform/setup/api-credentials.mdx index 820232bd13..74aa387e12 100644 --- a/fern/products/platform/pages/platform/setup/api-credentials.mdx +++ b/fern/products/platform/pages/platform/setup/api-credentials.mdx @@ -27,6 +27,9 @@ HTTP Basic Authentication requires you to send an Authorization header with your Each project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API. Some methods will also require you to pass your Space URL. +[Subprojects](/docs/platform/projects#subprojects) work the same way: each one has its own Project ID and tokens, +and a root project can issue a token for one of its subprojects with +[Create API token](/docs/apis/rest/project-tokens/create-token). - **Project ID:** Use this UUID to specify your Project to the API. - **Space URL:** Use this URL to access SignalWire APIs. diff --git a/fern/products/platform/pages/platform/setup/create-an-account.mdx b/fern/products/platform/pages/platform/setup/create-an-account.mdx index b2320e01b7..a53d90e791 100644 --- a/fern/products/platform/pages/platform/setup/create-an-account.mdx +++ b/fern/products/platform/pages/platform/setup/create-an-account.mdx @@ -49,7 +49,7 @@ Keep the following in mind: Once set, your Space domain cannot be changed except by a Support request. You can create multiple Spaces associated with your SignalWire account. - Each Space can contain multiple Projects. + Each Space can contain multiple Projects, and each Project can contain Subprojects. ### Create a project @@ -61,6 +61,16 @@ Now you have a SignalWire Space and your first project. Congratulations! +## Group work with projects and subprojects + +You can add more [projects](/docs/platform/projects) to your Space at any time, and a project can +hold [subprojects](/docs/platform/projects#subprojects): projects nested one level beneath it, +each with its own Project ID, API tokens, phone numbers, and resources. +Use subprojects to give every customer, environment, or region an isolated project, and to open +and retire those projects from the +[Projects API](/docs/apis/rest/projects/create-subproject) rather than the Dashboard. + + --- ## Next steps From a8e04c1e64221fe65511ba2d4dc9e53ac8a0c384 Mon Sep 17 00:00:00 2001 From: August Date: Fri, 4 Sep 2026 16:50:29 +0000 Subject: [PATCH 3/3] fix(docs): Capitalize Resource, Project, Subproject --- .../platform/pages/getting-started.mdx | 14 ++-- .../platform/pages/platform/core/projects.mdx | 74 +++++++++---------- .../pages/platform/setup/api-credentials.mdx | 8 +- .../platform/setup/create-an-account.mdx | 20 ++--- 4 files changed, 58 insertions(+), 58 deletions(-) diff --git a/fern/products/platform/pages/getting-started.mdx b/fern/products/platform/pages/getting-started.mdx index 47ade5aca3..cbb5ac7b82 100644 --- a/fern/products/platform/pages/getting-started.mdx +++ b/fern/products/platform/pages/getting-started.mdx @@ -272,18 +272,18 @@ const client = RestClient(PROJECT_ID, API_TOKEN, { ## Core concepts -### Projects and subprojects +### Projects and Subprojects -A **Project** groups everything you build: phone numbers, resources, and API credentials. +A **Project** groups everything you build: phone numbers, Resources, and API credentials. Every Space starts with one, and you can add more at any time. Beneath a Project you can nest **Subprojects**, one level deep. -A Subproject is a full project with its own Project ID, API tokens, and resources, which makes it +A Subproject is a full Project with its own Project ID, API tokens, and Resources, which makes it the way to isolate a customer, a tenant, or a staging environment. Unlike root Projects, Subprojects can be created and deleted through the API. - What a project scopes, and how subprojects nest beneath one + What a Project scopes, and how Subprojects nest beneath one ### Communication channels @@ -343,21 +343,21 @@ We also offer the option of purchasing phone numbers programmatically via our [P In SignalWire, a **Resource** is anything that can handle communications - an AI agent, a script, a SIP connection, or your own application. When a call or message comes in, you tell SignalWire which Resource should handle it. -Common resource types include: +Common Resource types include: - **SWML Scripts** - Simple JSON/YAML instructions hosted in your Dashboard - **AI Agents** - Conversational AI that handles calls autonomously - **Call Flows** - Visual drag-and-drop call routing - **Relay Applications** - Your own server applications connected via WebSocket - Understanding the different resource types + Understanding the different Resource types ### Addresses Every Resource has an **Address**. This is a unique identifier that lets you target and interact with it. -Think of addresses as the **phone number** for any resource, but broader in scope. +Think of addresses as the **phone number** for any Resource, but broader in scope. Addresses can be: - **Phone numbers** - Traditional numbers like `+14155551234` for PSTN calls diff --git a/fern/products/platform/pages/platform/core/projects.mdx b/fern/products/platform/pages/platform/core/projects.mdx index 8f6f173e53..e1cedb15bb 100644 --- a/fern/products/platform/pages/platform/core/projects.mdx +++ b/fern/products/platform/pages/platform/core/projects.mdx @@ -1,86 +1,86 @@ --- title: Projects -description: Projects group the phone numbers, resources, and credentials in your Space, and subprojects nest one level beneath a root project with their own Project ID and resources. +description: Projects group the phone numbers, Resources, and credentials in your Space, and Subprojects nest one level beneath a root Project with their own Project ID and Resources. slug: /projects max-toc-depth: 3 --- -A project is the container for what you build in a SignalWire Space. -Phone numbers, [resources](/docs/platform/resources), and -[API credentials](/docs/platform/your-signalwire-api-space) all belong to exactly one project, +A Project is the container for what you build in a SignalWire Space. +Phone numbers, [Resources](/docs/platform/resources), and +[API credentials](/docs/platform/your-signalwire-api-space) all belong to exactly one Project, which is how you group work by customer, by environment, or by any other classification you like. -Your Space starts with one project, created alongside the Space itself, and you can add more +Your Space starts with one Project, created alongside the Space itself, and you can add more from your Dashboard at any time. -## What a project scopes +## What a Project scopes -Each project carries its own Project ID and its own API tokens, and every request you make is -authenticated as one project and acts on that project alone. +Each Project carries its own Project ID and its own API tokens, and every request you make is +authenticated as one Project and acts on that Project alone. -Security settings are per-project too. -Each project has its own [media URL protection](/docs/platform/media-protection) settings for +Security settings belong to the Project too. +Each Project has its own [media URL protection](/docs/platform/media-protection) settings for recordings, message media, and fax media, and its own choice of whether webhooks and callbacks must use HTTPS. -Not everything divides along project lines. +Not everything divides along Project lines. Voice and messaging [rate limits](/docs/platform/rate-limits) are account-level, counted across -every project in your Space. +every Project in your Space. ## Subprojects -A subproject is a project nested one level beneath a root project. -It is a full project with its own Project ID and resources, but a subproject cannot contain other -subprojects. +A Subproject is a Project nested one level beneath a root Project. +It is a full Project with its own Project ID and Resources, but a Subproject cannot contain other +Subprojects. -Unlike root projects, subprojects can be created and deleted through the +Unlike root Projects, Subprojects can be created and deleted through the [Projects API](/docs/apis/rest/projects/list-projects), so an application can open and retire a -project per customer, per tenant, or per environment on its own. -Root projects are created in the Dashboard and can't be deleted through the API. +Project per customer, per tenant, or per environment on its own. +Root Projects are created in the Dashboard and can't be deleted through the API. -### Create a subproject +### Create a Subproject -Authenticate as the root project and send the subproject's name, along with any security settings +Authenticate as the root Project and send the Subproject's name, along with any security settings you want it to start with. -A subproject cannot create another subproject, so a request authenticated as a subproject fails +A Subproject cannot create another Subproject, so a request authenticated as a Subproject fails with `422 nested_subprojects_not_allowed`. -The response is the only place the new project's `signing_key` appears — it can't be retrieved +The response is the only place the new Project's `signing_key` appears — it can't be retrieved afterward, so capture it here. -To get credentials for the new subproject, call -[Create API token](/docs/apis/rest/project-tokens/create-token) from the root project with the -subproject's ID in `subproject_id`. +To get credentials for the new Subproject, call +[Create API token](/docs/apis/rest/project-tokens/create-token) from the root Project with the +Subproject's ID in `subproject_id`. -### Delete a subproject +### Delete a Subproject -Only subprojects can be deleted through the API; targeting the root project returns +Only Subprojects can be deleted through the API; targeting the root Project returns `422 only_subprojects_can_be_deleted`. -A project must have no phone numbers before it can be deleted, or the request returns +A Project must have no phone numbers before it can be deleted, or the request returns `422 phone_numbers_must_be_removed`. -Deleting a subproject also migrates its registry brands and campaigns up to the parent project. +Deleting a Subproject also migrates its registry brands and campaigns up to the parent Project. -## Manage projects through the API +## Manage Projects through the API -Every Projects API request reaches only the authenticated project and the subprojects beneath it. -[List projects](/docs/apis/rest/projects/list-projects) returns the authenticated project -alongside its subprojects, and each entry reports whether it is a subproject and which project it +Every Projects API request reaches only the authenticated Project and the Subprojects beneath it. +[List projects](/docs/apis/rest/projects/list-projects) returns the authenticated Project +alongside its Subprojects, and each entry reports whether it is a Subproject and which Project it belongs to. -A project ID outside that tree returns `404 Not Found`. +A Project ID outside that tree returns `404 Not Found`. [Update a project](/docs/apis/rest/projects/update-project) changes the name and security settings -of any project in that tree, root project included. +of any Project in that tree, root Project included. Integrations built around Compatibility API Account SIDs see the same tree as Accounts: [Create Subprojects](/docs/compatibility-api/rest/accounts/create-subprojects) and @@ -91,9 +91,9 @@ form-encoded requests. - Every operation for listing, creating, updating, and deleting projects. + Every operation for listing, creating, updating, and deleting Projects. - Find a project's Project ID and Space URL, and issue API tokens. + Find a Project's Project ID and Space URL, and issue API tokens. diff --git a/fern/products/platform/pages/platform/setup/api-credentials.mdx b/fern/products/platform/pages/platform/setup/api-credentials.mdx index 74aa387e12..a322508463 100644 --- a/fern/products/platform/pages/platform/setup/api-credentials.mdx +++ b/fern/products/platform/pages/platform/setup/api-credentials.mdx @@ -17,7 +17,7 @@ The API credentials found on this page are your key to accessing SignalWire's AP -Open **API Credentials** in the Dashboard to find the current project's **Project ID** and **Space URL**. Reveal and copy an existing API token or select **+ New** to create one. +Open **API Credentials** in the Dashboard to find the current Project's **Project ID** and **Space URL**. Reveal and copy an existing API token or select **+ New** to create one. @@ -25,17 +25,17 @@ Most SignalWire API endpoints require authentication using [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). HTTP Basic Authentication requires you to send an Authorization header with your Project ID and API Token. -Each project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API. +Each Project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API. Some methods will also require you to pass your Space URL. [Subprojects](/docs/platform/projects#subprojects) work the same way: each one has its own Project ID and tokens, -and a root project can issue a token for one of its subprojects with +and a root Project can issue a token for one of its Subprojects with [Create API token](/docs/apis/rest/project-tokens/create-token). - **Project ID:** Use this UUID to specify your Project to the API. - **Space URL:** Use this URL to access SignalWire APIs. For example: `https://{Your_Space_Name}.signalwire.com/api/calling/calls` - **API Tokens:** Authentication tokens to access the API. -You can have multiple tokens for each project. +You can have multiple tokens for each Project. diff --git a/fern/products/platform/pages/platform/setup/create-an-account.mdx b/fern/products/platform/pages/platform/setup/create-an-account.mdx index a53d90e791..b61023c493 100644 --- a/fern/products/platform/pages/platform/setup/create-an-account.mdx +++ b/fern/products/platform/pages/platform/setup/create-an-account.mdx @@ -52,22 +52,22 @@ Keep the following in mind: Each Space can contain multiple Projects, and each Project can contain Subprojects. -### Create a project +### Create a Project -Projects are used to group resources according to your preference, such as by customer account, by geographical region, or any other classification. -Name your project something that will help to distinguish it from the other projects you will make in the future, and you're ready to go. +Projects are used to group Resources according to your preference, such as by customer account, by geographical region, or any other classification. +Name your Project something that will help to distinguish it from the other Projects you will make in the future, and you're ready to go. -Now you have a SignalWire Space and your first project. Congratulations! +Now you have a SignalWire Space and your first Project. Congratulations! -## Group work with projects and subprojects +## Group work with Projects and Subprojects -You can add more [projects](/docs/platform/projects) to your Space at any time, and a project can -hold [subprojects](/docs/platform/projects#subprojects): projects nested one level beneath it, -each with its own Project ID, API tokens, phone numbers, and resources. -Use subprojects to give every customer, environment, or region an isolated project, and to open -and retire those projects from the +You can add more [Projects](/docs/platform/projects) to your Space at any time, and a Project can +hold [Subprojects](/docs/platform/projects#subprojects): Projects nested one level beneath it, +each with its own Project ID, API tokens, phone numbers, and Resources. +Use Subprojects to give every customer, environment, or region an isolated Project, and to open +and retire those Projects from the [Projects API](/docs/apis/rest/projects/create-subproject) rather than the Dashboard.