> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# list

> List the authenticated root project and its subprojects.

### projects.list

List the authenticated root project and its subprojects. Returns one page; use
`client.projects.paginate()` to iterate every project across pages.

### Schema

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /api/projects:
    get:
      operationId: subpackageProjects_list_projects
      summary: List projects
      description: >-
        Lists the authenticated root project and its subprojects.


        All endpoints operate only within the caller's project tree — the
        authenticated root

        project and the subprojects beneath it.


        Filter by name when locating a project, or use [Retrieve a
        project](/docs/apis/rest/projects/get-project) when you already have its
        ID. Integrations built around Compatibility API Account SIDs can use
        [List accounts](/docs/compatibility-api/rest/accounts/list-accounts)
        instead.


        #### Permissions


        The API token used to authenticate must have the following scope(s)
        enabled to make a successful request: _Management_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).
      tags:
        - subpackage_projects
      parameters:
        - name: name
          in: query
          description: Filter projects by name.
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: The number of results per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
        - name: page_token
          in: query
          description: >-
            Cursor token for paging, taken from the `links` in a previous
            response.
          required: false
          schema:
            type: string
        - name: page_number
          in: query
          description: The page index, used together with `page_token`.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects.ProjectListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
servers:
  - url: https://%7BYour_Space_Name%7D.signalwire.com
    description: SignalWire API
components:
  schemas:
    Projects.ProjectPaginationLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
          description: The link to the current page.
        first:
          type: string
          format: uri
          description: The link to the first page.
        next:
          type: string
          format: uri
          description: The link to the next page. Only present when more results exist.
        prev:
          type: string
          format: uri
          description: >-
            The link to the previous page. Only present when a previous page
            exists.
      required:
        - self
        - first
      description: Pagination links for a list of projects.
      title: Projects.ProjectPaginationLinks
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    Projects.Project:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifier of the project.
        name:
          type: string
          description: The name of the project.
        parent_project_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: >-
            The unique identifier of the root project. `null` when this project
            is itself a root project.
        subproject:
          type: boolean
          description: '`true` when this project is a subproject.'
        region_preference:
          type: string
          description: >-
            The effective region preference for the project. Returned in all
            responses; it is not currently settable through this API.
        protect_recordings:
          type: boolean
          description: >-
            When enabled, recordings created within the project require
            authentication to access.
        protect_message_media:
          type: boolean
          description: >-
            When enabled, message media created within the project requires
            authentication to access.
        protect_fax_media:
          type: boolean
          description: >-
            When enabled, fax media created within the project requires
            authentication to access.
        force_https_requests:
          type: boolean
          description: >-
            When enabled, requests made to the project's webhooks and callbacks
            must use HTTPS.
        created_at:
          type: string
          format: date-time
          description: The date and time when the project was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time when the project was last updated.
      required:
        - id
        - name
        - parent_project_id
        - subproject
        - region_preference
        - protect_recordings
        - protect_message_media
        - protect_fax_media
        - force_https_requests
        - created_at
        - updated_at
      description: A project or subproject within the caller's project tree.
      title: Projects.Project
    Projects.ProjectListResponse:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Projects.ProjectPaginationLinks'
          description: Pagination links for the list of projects.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Projects.Project'
          description: The projects on this page.
      required:
        - links
        - data
      description: A page of projects.
      title: Projects.ProjectListResponse
    TypesStatusCodesStatusCode401Error:
      type: string
      enum:
        - Unauthorized
      title: TypesStatusCodesStatusCode401Error
    Types.StatusCodes.StatusCode401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error'
      required:
        - error
      description: Access is unauthorized.
      title: Types.StatusCodes.StatusCode401
    TypesStatusCodesStatusCode500Error:
      type: string
      enum:
        - Internal Server Error
      title: TypesStatusCodesStatusCode500Error
    Types.StatusCodes.StatusCode500:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error'
      required:
        - error
      description: An internal server error occurred.
      title: Types.StatusCodes.StatusCode500

```

## Response Example

### Response (200)

```json
{
  "links": {
    "self": "https://example-space.signalwire.com/api/projects?page_size=50",
    "first": "https://example-space.signalwire.com/api/projects?page_size=50",
    "next": "https://example-space.signalwire.com/api/projects?page_size=50&page_number=1&page_token=PA8f14e45f",
    "prev": "https://example-space.signalwire.com/api/projects?page_size=50&page_number=0&page_token=PA8f14e45f"
  },
  "data": [
    {
      "id": "8f14e45f-ceea-467d-9c2b-7a1d3a9b2c34",
      "name": "Acme Staging",
      "parent_project_id": "b3877739-5c7e-4d4f-9d1a-2f0c8c2f1a11",
      "subproject": true,
      "region_preference": "us-west",
      "protect_recordings": false,
      "protect_message_media": false,
      "protect_fax_media": false,
      "force_https_requests": true,
      "created_at": "2024-05-06T12:20:00Z",
      "updated_at": "2024-05-06T12:20:00Z"
    }
  ]
}
```

## Example

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

result = client.projects.list()
for project in result.get("data", []):
    kind = "subproject" if project["subproject"] else "root"
    print(project["name"], project["id"], kind)
```