> 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 projects the caller can reach.


        With a project API token, that is the authenticated root project and its

        subprojects. With a Personal access token, it is every root project the
        token holder

        is enabled for, plus their subprojects.


        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


        With a project API token, the token must have the following scope(s)
        enabled to make a successful request: _Management_.


        With a [Personal access
        token](/docs/apis/authorization#personal-access-tokens) there are no
        scopes. The token holder must be an owner or admin of the space, and the
        request reaches only the projects the holder is enabled for, plus their
        subprojects.


        [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'
tags:
  - name: subpackage_projects
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)
```

> List the authenticated root project and its subprojects.