Skip to main content
No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

Create and manage projects via API

Create, update, archive, transfer, and delete BrowserStack projects, and manage project access, using the Project Management REST API.

Create a project

Create a project in your active team and enable one or more products on it. Your role must permit creating projects.

POST /v1/projects

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api.browserstack.com/v1/projects" \
-H "Content-Type: application/json" \
-d '{
  "name": "Docs Test Project 003",
  "description": "Regression suite for the checkout flow",
  "products": ["test_management", "automate"],
  "access": "restricted"
}'
  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • name* String

    The name of the project. It must be unique in your organization and can have up to 255 characters. For example, Mobile Beta Sprint 1.

    BrowserStack sanitizes the name before saving it. It removes leading and trailing spaces. The characters | ; > < ` + " ? % / \, and the newline, carriage return, and tab characters, are each replaced with _.

  • products* Array[String]

    The products to enable on the project, as a JSON array. Pass at least one value. You can use the canonical name or its abbreviation. Responses always return canonical names.

    Some products are enabled automatically with others. For example, enabling test_management also enables test_reporting_and_analytics.

    Product Canonical name Abbreviation
    Test Management test_management tcm
    Test Reporting & Analytics test_reporting_and_analytics tra
    Automate automate aut
    App Automate app_automate app_aut
    Accessibility Testing accessibility a11y
    App Accessibility Testing app_accessibility app_a11y
    Low Code Automation low_code_automation lca
    Percy percy percy
    App Percy app_percy app_percy
    Requestly requestly_api_platform requestly
    Website Scanner website_scanner web_scanner
  • description String

    The description of the project. For example, Cross-platform validation. A description longer than 16 KB is truncated.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private. The default value is org-wide. This parameter takes effect only when your organization uses project-level access control. In team-level mode, the response always shows restricted, and in global mode, it always shows org-wide. With project-level access control, restricted needs at least one access grant, and private needs none. A project created as restricted without an access grant is saved as private.

Response attributes 201 application/json

Response

{
  "id": "PR-116",
  "name": "Docs Test Project 003",
  "slug": "Docs-Test-Project-003-76b25215",
  "description": "Regression suite for the checkout flow",
  "access": "restricted",
  "products": [
    "test_management",
    "automate",
    "test_reporting_and_analytics"
  ],
  "archived": false,
  "created_at": "2026-09-25T11:21:21.000Z",
  "updated_at": "2026-09-25T11:21:21.000Z",
  "owner": "jane.doe@browserstack.com",
  "request_id": "ccb8c8fc-3212-4427-8798-378999602099"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Note: Responses always use canonical product names, even if you pass abbreviations. Enabling some products automatically enables related products. For example, enabling Test Management also enables Test Reporting & Analytics.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_CREATE_PERMISSION_DENIED Your role doesn’t permit creating projects.
409 PROJECT_NAME_EXISTS A project with this name already exists.
422 PROJECT_NAME_REQUIRED name is missing or blank.
422 PROJECT_NAME_TOO_LONG name is longer than 255 characters.
422 PRODUCTS_REQUIRED products is missing or empty.
422 INVALID_PRODUCT products contains an unknown product.
422 INVALID_ACCESS access isn’t org-wide, restricted, or private.

List projects

List the projects in your organization that you can view.

GET /v1/projects

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api.browserstack.com/v1/projects?page=1&page_size=30&sort_by=updated_at-DESC"
  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • page Integer

    The page number to return. Starts at 1. The default value is 1.

  • page_size Integer

    The number of projects per page, from 1 to 100. The default value is 30.

  • sort_by String

    The sort order, in the <field>-<direction> format, for example, name-ASC. The default value is updated_at-DESC.

    The supported fields are id, identifier, name, slug, created_at, updated_at, and archived. The direction is ASC or DESC and isn’t case-sensitive. If you omit the direction, the default is DESC. An unknown field or direction returns 422 INVALID_SORT.

  • archived Boolean

    Set to true to list only archived projects. The default value is false, which lists only active projects. Any value other than true is treated as false.

  • query String

    The text to search for in project names and project IDs. The match is a substring match, so Mobile matches iOS Mobile App, and PR-45 matches PR-452.

  • products Array[String]

    The products to filter by. The response includes projects that have any of these products enabled. For supported values, see the products table in Create a project. Pass the products in any of the following formats:

    Format Example
    Comma-separated list products=automate,percy
    JSON array string products=["automate","percy"]
    Repeated products[]= parameters products[]=automate&products[]=percy

    A repeated products= parameter without brackets returns 422 INVALID_PARAMS, and an unknown product name returns 422 INVALID_PRODUCT.

  • filter String

    A predefined filter. You can pass only one filter. The possible values are:

    Value Description
    my-projects Projects you own.
    shared-projects Projects you don’t own. If you belong to a team, the list includes only your team’s projects.
    edit-access-projects Projects where you have permission to update, archive, or delete the project, or to change its settings.

    An unsupported value, or more than one value using filter[]=, returns 422 INVALID_FILTER.

Response attributes 200 application/json

Response

{
  "data": [
    {
      "id": "PR-116",
      "name": "Docs Test Project 003",
      "slug": "Docs-Test-Project-003-76b25215",
      "description": "Regression suite for the checkout flow",
      "access": "restricted",
      "products": [
        "test_management",
        "automate",
        "test_reporting_and_analytics"
      ],
      "archived": false,
      "created_at": "2026-09-25T11:21:21.000Z",
      "updated_at": "2026-09-25T11:21:21.000Z",
      "owner": "jane.doe@browserstack.com"
    },
    {
      "id": "PR-115",
      "name": "Docs Test Project 002",
      "slug": "Docs-Test-Project-002-d88980c9",
      "description": null,
      "access": "restricted",
      "products": [
        "test_management",
        "automate",
        "test_reporting_and_analytics"
      ],
      "archived": false,
      "created_at": "2026-09-25T11:17:31.000Z",
      "updated_at": "2026-09-25T11:17:31.000Z",
      "owner": "jane.doe@browserstack.com"
    },
    {
      "id": "PR-112",
      "name": "Payments Smoke Tests",
      "slug": "Payments-Smoke-Tests-dcee0911",
      "description": "Smoke tests for the payments service",
      "access": "restricted",
      "products": [
        "test_management",
        "automate",
        "test_reporting_and_analytics"
      ],
      "archived": false,
      "created_at": "2026-09-25T11:07:54.000Z",
      "updated_at": "2026-09-25T11:07:54.000Z",
      "owner": "jane.doe@browserstack.com"
    },
    {
      "id": "PR-24",
      "name": "Default Project - LCA",
      "slug": "Default-Project---LCA-e36ab5b1",
      "description": null,
      "access": "restricted",
      "products": [
        "low_code_automation"
      ],
      "archived": false,
      "created_at": "2026-07-30T15:12:55.000Z",
      "updated_at": "2026-07-30T15:12:55.000Z",
      "owner": "jane.doe@browserstack.com"
    },
    {
      "id": "PR-20",
      "name": "Default Project",
      "slug": "Default-Project-c1419f70",
      "description": null,
      "access": "restricted",
      "products": [
        "automate"
      ],
      "archived": false,
      "created_at": "2026-07-23T10:57:26.000Z",
      "updated_at": "2026-07-27T09:00:35.000Z",
      "owner": "jane.doe@browserstack.com"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 30,
    "total": 5,
    "next": null,
    "prev": null
  },
  "request_id": "f83ff090-876c-4423-bbfc-814dd4c78cc6"
}
  • data Array[Object]

    A list of projects.

    â–¶ SHOW VALUES
    • id String

      The project identifier in the PR-<number> format. For example, PR-75.

    • name String

      The name of the project. For example, Mobile Beta Sprint 1.

    • slug String

      A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

    • description String

      The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

    • access String

      The access level of the project. The possible values are org-wide, restricted, or private.

    • products Array[String]

      The canonical names of the products enabled on the project. For example, test_management and automate.

    • archived Boolean

      Returns true if the project is archived, and false otherwise.

    • created_at String

      The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

    • updated_at String

      The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

    • owner String

      The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • pagination Object

    The pagination details.

    â–¶ SHOW VALUES
    • page Integer

      The current page number.

    • page_size Integer

      The number of items per page.

    • total Integer

      The total number of items. For project accesses, when all results fit on one page, total equals the number of rows returned. Otherwise, the project owner isn’t counted in total.

    • next Integer

      The next page number. Returns null on the last page.

    • prev Integer

      The previous page number. Returns null on the first page.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
422 INVALID_PAGE page is less than 1.
422 INVALID_PAGE_SIZE page_size is outside the 1 to 100 range.
422 INVALID_SORT sort_by uses an unknown field or direction.
422 INVALID_FILTER filter isn’t one of the supported values, or you passed more than one filter.
422 INVALID_PRODUCT products contains an unknown product.
422 INVALID_PARAMS products is repeated without brackets, for example, products=a&products=b.

Get a project

Get the details of a project, including its current owner.

GET /v1/projects/{pid}

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api.browserstack.com/v1/projects/PR-3"
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Response attributes 200 application/json

Response

{
  "id": "PR-3",
  "name": "Checkout Regression",
  "slug": "sas-41fca5a8",
  "description": "",
  "access": "restricted",
  "products": [
    "app_accessibility",
    "test_management",
    "test_reporting_and_analytics"
  ],
  "archived": false,
  "created_at": "2025-12-10T10:21:09.000Z",
  "updated_at": "2025-12-10T10:21:09.000Z",
  "owner": "jane.doe@browserstack.com",
  "created_by": {
    "email": "jane.doe@browserstack.com",
    "full_name": "Jane Doe"
  },
  "request_id": "5acabf85-e051-4d09-9ca1-068bcfa9dec7"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • created_by Object

    The current project owner’s email address and full name. After an ownership transfer, this object shows the new owner. Omitted if the owner’s user record can’t be found.

    â–¶ SHOW VALUES
    • email String

      The email address of the current project owner. For example, jane.doe@browserstack.com.

    • full_name String

      The full name of the current project owner. For example, Jane Doe.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.
422 INVALID_PROJECT_ID pid isn’t in the PR-<number> format.

Update a project

Update the name, description, access level, or products of a project. Fields that you don’t pass remain unchanged.

PATCH /v1/projects/{pid}

Note: You can only add products. The products you pass are added to the existing products. You can’t remove a product with this endpoint. To archive, unarchive, or delete a project, use the dedicated endpoints. You can also send this request with the PUT method, which behaves the same as PATCH.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH "https://api.browserstack.com/v1/projects/PR-3" \
-H "Content-Type: application/json" \
-d '{
  "description": "Regression suite for the checkout flow. Covers manual test cases in Test Management, Automate runs on Chrome and Safari, and visual checks in Percy.",
  "products": ["percy"]
}'
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • name String

    The new name of the project. The name must be unique in your organization and can have up to 255 characters. For example, Mobile Beta Sprint 2. An empty name returns 422 PROJECT_NAME_REQUIRED. Renaming a project doesn’t change its slug.

    BrowserStack sanitizes the name before saving it. It removes leading and trailing spaces. The characters | ; > < ` + " ? % / \, and the newline, carriage return, and tab characters, are each replaced with _.

  • description String

    The new description of the project. For example, Updated description. BrowserStack truncates descriptions longer than 16 KB. To clear the description, pass an empty string (""). The API ignores null and leaves the description unchanged.

  • access String

    The new access level of the project. The possible values are org-wide, restricted, or private. This parameter takes effect only when your organization uses project-level access control. In team-level mode, the response always shows restricted, and in global mode, it always shows org-wide. With project-level access control, restricted needs at least one access grant, and private needs none. A project set to restricted without an access grant is saved as private.

  • products Array[String]

    The products to add to the project, as a JSON array. The products you pass are added to the existing products. No product is removed. Some products are enabled automatically with others. For example, enabling test_management also enables test_reporting_and_analytics. For supported values, see the products table in Create a project.

Response attributes 200 application/json

Response

{
  "id": "PR-3",
  "name": "Checkout Regression",
  "slug": "sas-41fca5a8",
  "description": "Regression suite for the checkout flow. Covers manual test cases in Test Management, Automate runs on Chrome and Safari, and visual checks in Percy.",
  "access": "restricted",
  "products": [
    "app_accessibility",
    "test_management",
    "test_reporting_and_analytics",
    "percy"
  ],
  "archived": false,
  "created_at": "2025-12-10T10:21:09.000Z",
  "updated_at": "2026-09-25T11:34:01.000Z",
  "owner": "jane.doe@browserstack.com",
  "request_id": "70221b48-c53e-490d-8924-65ba71d973cc"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
403 `` You don’t have permission to modify the project.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.
409 PROJECT_INVALID_STATE The project is archived.
409 PROJECT_NAME_EXISTS A project with the new name already exists.
422 INVALID_PROJECT_ID pid isn’t in the PR-<number> format.
422 PROJECT_NAME_REQUIRED name is an empty string.
422 PROJECT_NAME_TOO_LONG name is longer than 255 characters.
422 PRODUCTS_REQUIRED products is an empty array.
422 INVALID_PRODUCT products contains an unknown product.
422 INVALID_ACCESS access isn’t org-wide, restricted, or private.
422 INVALID_PARAMS The request body changes archived or deleted. Passing the current value is allowed.

Delete a project

Delete a project. You can delete an archived project directly, without unarchiving it first.

DELETE /v1/projects/{pid}

Warning: Deleting a project also permanently deletes its test cases, folders, test runs, test plans, environments, and build data. BrowserStack removes the data in the background after the request completes, and you can’t restore it. To keep the data, archive the project instead.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE "https://api.browserstack.com/v1/projects/PR-1"
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Response attributes 200 application/json

Response

{
  "id": "PR-1",
  "deleted_at": "2026-09-25T11:35:39Z",
  "request_id": "cffaf95e-26c9-4458-a545-f3c9ecc771d2"
}
  • id String

    The identifier of the deleted project. For example, PR-75.

  • deleted_at String

    The time the project was deleted, in ISO 8601 format. For example, 2026-09-23T08:45:58Z.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
403 PROJECT_DELETE_PERMISSION_DENIED You don’t have permission to delete the project.
404 PROJECT_NOT_FOUND The project doesn’t exist or is already deleted.
422 INVALID_PROJECT_ID pid isn’t in the PR-<number> format.

Archive a project

Archive a project. You can’t modify, transfer, or change access to an archived project until you unarchive it. The request has no body. If the project is already archived, the API returns 200 and the project remains unchanged.

PUT /v1/projects/{pid}/archive

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api.browserstack.com/v1/projects/PR-5/archive"
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Response attributes 200 application/json

Response

{
  "id": "PR-5",
  "name": "Testing Project 2026-09-25T11:36:39.320Z",
  "slug": "Testing-Project-9bf97d1c",
  "description": null,
  "access": "restricted",
  "products": [
    "test_reporting_and_analytics",
    "automate",
    "test_management"
  ],
  "archived": true,
  "created_at": "2026-03-09T07:15:21.000Z",
  "updated_at": "2026-09-25T11:36:39.000Z",
  "owner": "jane.doe@browserstack.com",
  "request_id": "b99ee249-4e12-4b46-82ce-ea5b7ffe9942"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Note: Archiving renames the project to <name> <timestamp>, for example, Testing Project 2026-09-25T11:36:39.320Z. Unarchiving doesn’t restore the original name.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
403 PROJECT_ARCHIVE_PERMISSION_DENIED You don’t have permission to archive the project.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.

Unarchive a project

Restore an archived project. The request has no body. If the project isn’t archived, the API returns 200 and the project remains unchanged. Unarchiving doesn’t restore the project’s original name. The timestamp that archiving added to the name stays in place.

PUT /v1/projects/{pid}/unarchive

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api.browserstack.com/v1/projects/PR-5/unarchive"
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

Response attributes 200 application/json

Response

{
  "id": "PR-5",
  "name": "Testing Project 2026-09-25T11:36:39.320Z",
  "slug": "Testing-Project-9bf97d1c",
  "description": null,
  "access": "restricted",
  "products": [
    "test_reporting_and_analytics",
    "automate",
    "test_management"
  ],
  "archived": false,
  "created_at": "2026-03-09T07:15:21.000Z",
  "updated_at": "2026-09-25T11:38:04.000Z",
  "owner": "jane.doe@browserstack.com",
  "request_id": "de392faf-6af5-488a-9d60-f6300aa8e333"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
403 PROJECT_ARCHIVE_PERMISSION_DENIED You don’t have permission to unarchive the project.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.

Transfer a project

Transfer the ownership of a project to another user, or move the project to another team:

  • To transfer ownership, set transfer_type to ownership and pass the new owner’s email in user_email. In team-level access mode, if the new owner belongs to a team, that team must be one of the project’s teams. Users without a team can receive any project.
  • To move the project to another team, set transfer_type to team_mapping and pass the team name in team_name. To move the project to the organization level, pass Bstack_org as team_name. Moving a project between teams is available only when project data access is set to team level, and only organization-level Owners and Admins can do it. Everyone else gets a 403 error.

PUT /v1/projects/{pid}/transfer

Warning: Moving a project to another team removes all explicit access grants on it.

Request parameters

Request

# Transfer ownership
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api.browserstack.com/v1/projects/PR-78/transfer" \
-H "Content-Type: application/json" \
-d '{
  "transfer_type": "ownership",
  "user_email": "john.smith@browserstack.com"
}'

# Move the project to another team
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api.browserstack.com/v1/projects/PR-78/transfer" \
-H "Content-Type: application/json" \
-d '{
  "transfer_type": "team_mapping",
  "team_name": "Payments QA"
}'
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • transfer_type String

    The type of transfer. The possible values are ownership and team_mapping. The default value is ownership. Required when you pass team_name.

  • user_email String

    The email address of the new owner. Required when transfer_type is ownership. For example, john.smith@browserstack.com. In team-level access mode, if the new owner belongs to a team, that team must be one of the project’s teams. Users without a team can receive any project.

  • team_name String

    The name of the team to move the project to. Required when transfer_type is team_mapping. For example, Payments QA. To move the project to the organization level, pass Bstack_org as team_name. If you pass your organization name instead, the API treats it as a team name and returns 404 TEAM_NOT_FOUND. Only organization-level Owners and Admins can move a project to another team.

Response attributes 200 application/json

Response

{
  "id": "PR-78",
  "name": "Checkout Web Suite",
  "slug": "Checkout-Web-Suite-4c21dd3d",
  "description": null,
  "access": "restricted",
  "products": [
    "test_management",
    "automate",
    "test_reporting_and_analytics"
  ],
  "archived": false,
  "created_at": "2026-09-23T08:47:25.000Z",
  "updated_at": "2026-09-23T08:47:27.000Z",
  "owner": "john.smith@browserstack.com",
  "request_id": "3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f"
}
  • id String

    The project identifier in the PR-<number> format. For example, PR-75.

  • name String

    The name of the project. For example, Mobile Beta Sprint 1.

  • slug String

    A URL-friendly identifier that BrowserStack generates from the project name when the project is created. The slug doesn’t change when you rename the project. For example, Mobile-Beta-Sprint-1-9db22b66.

  • description String

    The description of the project. For example, Cross-platform validation. Returns null if the project has no description.

  • access String

    The access level of the project. The possible values are org-wide, restricted, or private.

  • products Array[String]

    The canonical names of the products enabled on the project. For example, test_management and automate.

  • archived Boolean

    Returns true if the project is archived, and false otherwise.

  • created_at String

    The time the project was created, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • updated_at String

    The time the project was last updated, in ISO 8601 format. For example, 2026-09-23T08:45:49.000Z.

  • owner String

    The email address of the current project owner. Returns null if the owner’s user record can’t be found. For example, jane.doe@browserstack.com.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
403 PROJECT_ACCESS_DENIED_SHOW You don’t have access to the project.
403 PROJECT_TRANSFER_PERMISSION_DENIED You don’t have permission to transfer the project, or you aren’t an organization-level Owner or Admin for a team_mapping transfer.
404 USER_NOT_FOUND No user with the email in user_email exists in your organization.
404 TEAM_NOT_FOUND No team with the name in team_name exists in your organization. The API also returns this error if you pass your organization name instead of Bstack_org.
409 ALREADY_PROJECT_OWNER The user is already the owner of the project.
409 TEAM_MISMATCH In team-level access mode, the new owner’s team isn’t one of the project’s teams.
409 TEAM_MAPPING_NOT_AVAILABLE Project data access isn’t set to team level.
409 PROJECT_INVALID_STATE The project is archived.
422 INVALID_TRANSFER_TYPE transfer_type isn’t ownership or team_mapping.
422 USER_EMAIL_REQUIRED user_email is missing for an ownership transfer.
422 TEAM_NAME_REQUIRED team_name is missing for a team transfer.
422 VIEWER_ROLE_INELIGIBLE The new owner has the Viewer role.

List project accesses

List the users, teams, and service accounts that have explicit access to a project. To check specific accessors, filter by user_emails or team_names.

GET /v1/projects/{pid}/accesses

Note: Keep the following points in mind when you list project access:

  • The first page always includes the project owner, even if the owner has no explicit access entry.
  • When all results fit on one page, pagination.total equals the number of rows returned. Otherwise, the owner isn’t counted in pagination.total, so the first page can contain page_size + 1 rows.
  • For an org-wide project with no explicit access entries, the response lists your organization as an organization accessor.
  • When you filter by user_emails or team_names, the API ignores page, doesn’t add the owner automatically, and leaves out values that don’t match an accessor.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api.browserstack.com/v1/projects/PR-78/accesses"
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • page Integer

    The page number to return. Starts at 1. The default value is 1. Ignored when you filter by user_emails or team_names.

  • page_size Integer

    The number of accessors per page, from 1 to 100. The default value is 30.

  • user_emails Array[String]

    The user email addresses to filter by. Pass a comma-separated list, a JSON array string, or repeated user_emails[]= parameters. You can pass up to 10,000 values. For example, user_emails=jane.doe@browserstack.com,john.smith@browserstack.com. When you filter, page is ignored, the project owner isn’t added automatically, and email addresses that don’t match an accessor are left out of the response. A repeated user_emails= parameter without brackets returns 422 INVALID_PARAMS.

  • team_names Array[String]

    The team names to filter by. Pass a comma-separated list, a JSON array string, or repeated team_names[]= parameters. You can pass up to 10,000 values. For example, team_names=Payments QA,Mobile QA. When you filter, page is ignored, the project owner isn’t added automatically, and team names that don’t match an accessor are left out of the response. A repeated team_names= parameter without brackets returns 422 INVALID_PARAMS.

Response attributes 200 application/json

Response

{
  "data": [
    {
      "accessor_type": "user",
      "name": "Jane Doe",
      "email": "jane.doe@browserstack.com",
      "applicable_role": "Admin",
      "access": true,
      "overridden_role": null,
      "assigned_at": null
    },
    {
      "accessor_type": "team",
      "name": "Payments QA",
      "applicable_role": null,
      "access": true,
      "overridden_role": "Viewer",
      "assigned_at": "2026-09-23T08:47:26.000Z"
    },
    {
      "accessor_type": "user",
      "name": "John Smith",
      "email": "john.smith@browserstack.com",
      "applicable_role": "Admin",
      "access": true,
      "overridden_role": "Admin",
      "assigned_at": "2026-09-23T08:47:26.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 30,
    "total": 3,
    "next": null,
    "prev": null
  },
  "request_id": "3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f"
}
  • data Array[Object]

    A list of users, teams, and service accounts with access to the project.

    â–¶ SHOW VALUES
    • accessor_type String

      The type of accessor. The possible values are user, team, service_account, or organization.

    • name String

      The full name of the user, the name of the team, or the name of the organization. Absent for service accounts. For example, Jane Doe for a user or Payments QA for a team.

    • email String

      The email address of the user or service account. Absent for teams. For example, jane.doe@browserstack.com.

    • access Boolean

      Returns true if the accessor has access to the project. Returns false if the project access level or access rules deny access.

    • overridden_role String

      The project-level role override. For example, Admin or Viewer. Returns null if the accessor has no override.

    • applicable_role String

      The effective role on the project, after global roles and the project override are applied. For example, Admin. Returns null for teams and organizations, or when access is false.

    • assigned_at String

      The time the project access was assigned, in ISO 8601 format. For example, 2026-09-23T08:47:26.000Z. Returns null if no assignment time is recorded.

  • pagination Object

    The pagination details. When all results fit on one page, total equals the number of rows returned. Otherwise, the project owner isn’t counted in total, so page 1 can have page_size + 1 rows.

    â–¶ SHOW VALUES
    • page Integer

      The current page number.

    • page_size Integer

      The number of items per page.

    • total Integer

      The total number of items. For project accesses, when all results fit on one page, total equals the number of rows returned. Otherwise, the project owner isn’t counted in total.

    • next Integer

      The next page number. Returns null on the last page.

    • prev Integer

      The previous page number. Returns null on the first page.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following endpoint-specific errors:

Status error.code Cause
400 TOO_MANY_FILTERS user_emails or team_names contains more than 10,000 values.
403 PROJECT_ACCESS_DENIED You don’t have permission to view project accesses.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.
422 INVALID_PAGE page is less than 1.
422 INVALID_PAGE_SIZE page_size is outside the 1 to 100 range.
422 INVALID_PARAMS user_emails or team_names is repeated without brackets, for example, user_emails=a&user_emails=b.

Grant or update project accesses

Grant project access to users, teams, and service accounts, or update their project-level roles. Accessors that you don’t list keep their current access. You can pass up to 10,000 accessors in one request, as a JSON object in the {"accesses": [...]} format. If you omit overridden_role for an accessor, the API removes any existing override on that accessor. Granting access to a private project changes it to restricted.

PUT /v1/projects/{pid}/accesses

Note: The API validates each accessor separately and returns 200 even if some accessors fail. The API saves all valid entries. Check the status and error of each item in data. If the API rejects the whole request, for example, because you don’t have permission to update the project, it returns that error and no data. If you list the same accessor more than once, the last entry applies.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PUT "https://api.browserstack.com/v1/projects/PR-78/accesses" \
-H "Content-Type: application/json" \
-d '{
  "accesses": [
    { "accessor_type": "user", "email": "john.smith@browserstack.com", "overridden_role": "Admin" },
    { "accessor_type": "team", "name": "Payments QA", "overridden_role": "Viewer" },
    { "accessor_type": "user", "email": "alex.johnson@browserstack.com" }
  ]
}'
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • accesses* Array[Object]

    The users, teams, and service accounts to grant access to, or whose role to update. Pass 1 to 10,000 entries. The request body must be a JSON object in the {"accesses": [...]} format.

    â–¶ SHOW VALUES
    • accessor_type* String

      The type of accessor. The possible values are user, team, or service_account.

    • email String

      The email address of the user or service account. Required when accessor_type is user or service_account. For example, john.smith@browserstack.com.

    • name String

      The name of the team. Required when accessor_type is team. For example, Payments QA.

    • overridden_role String

      The project-level role to assign, for example, Admin or Viewer. Assign a user role to users and teams, and a service account role, such as SVC_Admin, to service accounts. If you omit it, the API removes any existing override and the accessor gets its default role. A user with the Viewer role, or an SVC_Viewer service account, can’t be given a higher project role.

Response attributes 200 application/json

Response

{
  "data": [
    {
      "accessor_type": "user",
      "email": "john.smith@browserstack.com",
      "status": 200
    },
    {
      "accessor_type": "team",
      "name": "Payments QA",
      "status": 200
    },
    {
      "accessor_type": "user",
      "email": "alex.johnson@browserstack.com",
      "status": 404,
      "error": {
        "code": "USER_NOT_FOUND",
        "message": "Target user not found",
        "target": "email"
      }
    }
  ],
  "summary": {
    "requested": 3,
    "succeeded": 2,
    "failed": 1
  },
  "request_id": "3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f"
}
  • data Array[Object]

    The result for each accessor, in the order of the request.

    â–¶ SHOW VALUES
    • accessor_type String

      The type of accessor. The possible values are user, team, or service_account.

    • email String

      The email address of the user or service account. For example, john.smith@browserstack.com.

    • name String

      The name of the team. For example, Payments QA.

    • status Integer

      The HTTP status for this accessor. 200 means the operation succeeded. Other values, such as 403 or 404, mean the operation failed for this accessor.

    • error Object

      The error details. Present only when the operation failed for this accessor.

      â–¶ SHOW VALUES
      • code String

        A machine-readable error code, for example, USER_NOT_FOUND.

      • message String

        A human-readable error message. For example, Target user not found.

      • target String

        The request field that the error refers to, if any. For example, email.

  • summary Object

    The count of requested, succeeded, and failed accessors.

    â–¶ SHOW VALUES
    • requested Integer

      The number of accessors in the request.

    • succeeded Integer

      The number of accessors processed successfully.

    • failed Integer

      The number of accessors that failed.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the following request-level errors:

Status error.code Cause
400 ACCESSES_REQUIRED accesses is missing or empty.
400 TOO_MANY_ACCESSORS accesses contains more than 10,000 entries.
403 PROJECT_UPDATE_PERMISSION_DENIED You don’t have permission to manage project access.
404 PROJECT_NOT_FOUND The project doesn’t exist or is deleted.
409 PROJECT_INVALID_STATE The project is archived.

Each item in data can return the following errors:

Status error.code Cause
400 INVALID_ACCESSOR_TYPE accessor_type isn’t user, team, or service_account.
403 PROJECT_UPDATE_PERMISSION_DENIED The user or team isn’t in the same team as the project.
404 USER_NOT_FOUND No user with this email exists in your organization.
404 TEAM_NOT_FOUND No team with this name exists in your organization.
404 SERVICE_ACCOUNT_NOT_FOUND No service account with this email exists.
422 INVALID_ROLE overridden_role is unknown.
422 INVALID_ROLE_FOR_SERVICE_ACCOUNT A user role is assigned to a service account.
422 INVALID_ROLE_FOR_USER A service account role is assigned to a user.
422 VIEWER_ROLE_INELIGIBLE The accessor is a Viewer or an SVC_Viewer service account, and you can’t assign it a higher project role.

Revoke project accesses

Revoke project access from users, teams, and service accounts. Pass the accessors in the request body in the {"accesses": [...]} format. If the request has no body, you can pass them in the user_emails and team_names query parameters instead. Revoking the last access grant on a restricted project changes it to private.

DELETE /v1/projects/{pid}/accesses

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE "https://api.browserstack.com/v1/projects/PR-78/accesses" \
-H "Content-Type: application/json" \
-d '{
  "accesses": [
    { "accessor_type": "user", "email": "john.smith@browserstack.com" },
    { "accessor_type": "user", "email": "alex.johnson@browserstack.com" }
  ]
}'
  • pid* String

    The project identifier in the PR-<number> format. For example, PR-75. Pass it in the URL path.

  • request_id String

    An optional correlation ID for the request, passed as a query parameter. The API returns it as request_id in the response. If you omit it, the API generates a UUID. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

  • accesses Array[Object]

    The users, teams, and service accounts whose access to revoke. Pass 1 to 10,000 entries in the {"accesses": [...]} format. Required unless you pass user_emails or team_names.

    â–¶ SHOW VALUES
    • accessor_type* String

      The type of accessor. The possible values are user, team, or service_account.

    • email String

      The email address of the user or service account. Required when accessor_type is user or service_account. For example, john.smith@browserstack.com.

    • name String

      The name of the team. Required when accessor_type is team. For example, Payments QA.

    • overridden_role String

      Ignored for revoke.

  • user_emails Array[String]

    The email addresses of the users whose access to revoke, passed as a query parameter instead of accesses. Used only when the request has no body. For example, user_emails=john.smith@browserstack.com.

  • team_names Array[String]

    The names of the teams whose access to revoke, passed as a query parameter instead of accesses. Used only when the request has no body. For example, team_names=Payments QA.

Response attributes 200 application/json

Response

{
  "data": [
    {
      "accessor_type": "user",
      "email": "john.smith@browserstack.com",
      "status": 200
    },
    {
      "accessor_type": "user",
      "email": "alex.johnson@browserstack.com",
      "status": 404,
      "error": {
        "code": "USER_NOT_FOUND",
        "message": "Target user not found",
        "target": "email"
      }
    }
  ],
  "summary": {
    "requested": 2,
    "succeeded": 1,
    "failed": 1
  },
  "request_id": "3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f"
}
  • data Array[Object]

    The result for each accessor, in the order of the request.

    â–¶ SHOW VALUES
    • accessor_type String

      The type of accessor. The possible values are user, team, or service_account.

    • email String

      The email address of the user or service account. For example, john.smith@browserstack.com.

    • name String

      The name of the team. For example, Payments QA.

    • status Integer

      The HTTP status for this accessor. 200 means the operation succeeded. Other values, such as 403 or 404, mean the operation failed for this accessor.

    • error Object

      The error details. Present only when the operation failed for this accessor.

      â–¶ SHOW VALUES
      • code String

        A machine-readable error code, for example, USER_NOT_FOUND.

      • message String

        A human-readable error message. For example, Target user not found.

      • target String

        The request field that the error refers to, if any. For example, email.

  • summary Object

    The count of requested, succeeded, and failed accessors.

    â–¶ SHOW VALUES
    • requested Integer

      The number of accessors in the request.

    • succeeded Integer

      The number of accessors processed successfully.

    • failed Integer

      The number of accessors that failed.

  • request_id String

    The correlation ID of the request. Share it with BrowserStack support when you report an issue. For example, 3f6d2c1e-8a9b-4c7d-9e0f-1a2b3c4d5e6f.

The API returns the same request-level errors as Grant or update project accesses.

Each item in data can return the following errors:

Status error.code Cause
400 INVALID_ACCESSOR_TYPE accessor_type isn’t user, team, or service_account.
403 PROJECT_UPDATE_PERMISSION_DENIED In team-level access mode, the user or team isn’t in the same team as the project.
404 USER_NOT_FOUND No user with this email exists in your organization.
404 TEAM_NOT_FOUND No team with this name exists in your organization.
404 SERVICE_ACCOUNT_NOT_FOUND No service account with this email exists.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback

Download Copy Check Circle