Project

Each project represents a logical grouping of builds executed on Percy. Use our REST API to manage your projects and fetch the project details in real-time.

Get project details

GET https://percy.io/api/v1/projects

Retrieves the details of the project associated with the given token. If no token is provided, this API returns details of all public projects.

Request parameters

No parameters required.

Curl Request

curl --request GET \
     --url https://percy.io/api/v1/projects \
     --header 'Authorization: Token token=<PROJECT_TOKEN>'

Response attributes `200 OK` `JSON`

Response

{
  "data": {
    "type": "projects",
    "id": "4xxxxxx",
    "attributes": {
      "name": "test-auto",
      "slug": "test-auto",
      "type": "automate",
      "full-slug": "9xxxxxxxx/test-auto",
      "is-enabled": true,
      "diff-base": "automatic",
      "auto-approve-branch-filter": "",
      "approval-required-branch-filter": "*",
      "default-base-branch": "master",
      "created-at": "2020-12-25T11:24:41.000Z",
      "updated-at": "2023-10-03T10:17:51.000Z",
      "publicly-readable": false,
      "is-demo": false,
      "is-auto-browser-upgrade": true,
      "wait-for-base-build": false,
      "current-period-usage": 5,
      "screenshot-limit": null,
      "workflow": "git",
      "intelli-ignore-enabled": false,
      "intelli-ignore-diff-ignore-percentage": 0,
      "default-ignore-diff-ignore-percentage": 0.2,
      "diff-sensitivity-level": 2,
      "delay-seconds": "3.0",
      "visual-monitoring-urls-count": null,
      "schedule": null,
      "next-schedule-time": null,
      "latest-build-stat": null,
      "visual-monitoring-urls": [],
      "vm-staging-base-url": null,
      "vm-last-build-baseline": false,
      "vm-diff-ignore-enabled": null,
      "vm-diff-ignore-percentage": null,
      "auth-type": null,
      "auth-config-name": null,
      "auth-params": null,
      "sitemap-ids": null,
      "cron": null,
      "schedule-start": null,
      "schedule-end": null,
      "tag-ids": []
    },
    "links": {
      "self": "/api/v1/projects/9xxxxxxxx/test-auto"
    },
    "relationships": {
       "repo": {
        "links": {
          "related": "/api/v1/projects/9xxxxxxx/test-auto/repo"
        },
        "data": {
          "type": "repos",
          "id": "39xxxx"
        }
      },
      "organization": {
        "links": {
          "related": "/api/v1/projects/9xxxxxxxx/test-auto/organization"
        },
        "data": {
          "type": "organizations",
          "id": "30xxx"
        }
      },
      "builds": {
        "links": {
          "related": "/api/v1/builds?project_id=4xxxxxx"
        }
      },
      "tokens": {
        "links": {
          "related": "/api/v1/projects/9xxxxxxxx/test-auto/tokens"
        }
      },
      "browser-targets": {
        "data": [
          {
            "type": "browser-targets",
            "id": "6x"
          }
        ]
      },
      "project-browser-targets": {
        "data": [
          {
            "type": "project-browser-targets",
            "id": "7xxxxxx"
          }
        ]
      },
      "webhook-configs": {
        "data": []
      }
    }
  },
  "included": [
    {
      "type": "repos",
      "id": "39xxxx",
      "attributes": {
        "name": "example",
        "slug": "browserstack/example",
        "html-url": "https://github.com/browserstack/example",
        "hostname": "github.com",
        "source": "github"
      },
      "relationships": {
        "version-control-integration": {
          "links": {
            "self": "/relationships/version-control-integration",
            "related": "/version-control-integration"
          },
          "data": {
            "type": "version-control-integrations",
            "id": "49xx"
          }
        }
      }
    },
    {
      "type": "browser-targets",
      "id": "60",
      "attributes": {
        "version-target": "121.0.6167.85",
        "deprecation-period-start": null,
        "deprecation-period-end": null
      },
      "relationships": {
        "operating-system": {},
        "browser-family": {
          "data": {
            "type": "browser-families",
            "id": "2"
          }
        }
      }
    },
    {
      "type": "browser-families",
      "id": "2",
      "attributes": {
        "name": "Chrome",
        "slug": "chrome"
      }
    },
    {
      "type": "project-browser-targets",
      "id": "74xxxxx",
      "relationships": {
        "browser-target": {
          "data": {
            "type": "browser-targets",
            "id": "6x"
          }
        },
        "project": {
          "data": {
            "type": "projects",
            "id": "1xxxxx"
          }
        }
      }
    }
  ]
}

attributes Object

Details of test session.

▶ SHOW VALUES
- name String
  
  Name of the project.
- slug String
  
  Slug of the project.
- type String
  
  Web or App project.
- full-slug String
  
  Path of full slug.
- is-enabled Boolean
  
  Project is archieved or not.
- diff-base String
  
  (Can be ignored. Used for projects prior to 2019).
- auto-approve-branch-filter String
  
  Specifies the name of the branches for auto-approval.
- approval-required-branch-fitler String
  
  Specifies the name of the branches where manual approval is required.
- default-base-branch String
  
  Specifies the name of the default baseline branch.
- updated-at Integer
  
  Time stamp when the project was last updated.
- publicly-readable Boolean
  
  Specifies if the project is publicly viewable.
- is-demo Boolean
  
  Specifies if the project is a demo project.
- is-auto-browser-upgrade Boolean
  
  Specifies if the browser version is set to auto-upgrade.
- wait-for-base-build Boolean
  
  Specifies if the “wait for base build” option has been configured in the project settings.
- current-period-usage Boolean
  
  Specifies the current period usage for a project.
- screenshot-limit Boolean
  
  Specifies the screenshot limit for a project.
- workflow Boolean
  
  Specifies workflow that has been configured in the project settings.
- diff-sensitivity-levels Integer
  
  Specifies the diff-sensitivity-levels based on your project settings.
- visual-monitoring-urls String
  
  Specifies the URLs targetted for visual monitoring.
- latest-build-stat String
  
  Specifies the latest build stats.
- vm-last-build-baseline String
  
  Specifies the baseline for a monitoring project.
- created-at Integer
  
  Specifies the project creation time stamp.
links Object

Details of test session.

▶ SHOW VALUES
- self String
  
  Time stamp when the build was last updated.
relationships Object

Details of test session.

▶ SHOW VALUES
- organisation Object
  
  Specifies details of the org and the API endpoint.
- repo Object
  
  Specifies details of the repo and URL path for the API endpoint.
- builds Object
  
  Specifies API endpoint to fetch builds.
- tokens Object
  
  Specifies API endpoint to fetch the token.
- browser-targets Object
  
  Specifies browser-targets and respective IDs
- project-browser-targets Object
  
  Specifies project-browser-targets and respective IDs.
- webhook-configs Object
  
  Specifies on what events would we be notified, » project settings.

Create a project

POST https://percy.io/api/v1/projects

Create a web or app project programmatically. Use this API to provision projects from your own tooling instead of creating them manually in the Percy dashboard.

Note: Authentication
This endpoint requires your BrowserStack username and access key passed through HTTP Basic auth. The project tokens shown in Project Settings are scoped to an existing project and cannot create a new one. The authenticating user must be a member, admin, or owner of the organization with project-creation rights.

Request parameters

Curl Request

curl --user "<BROWSERSTACK_USERNAME>:<BROWSERSTACK_ACCESS_KEY>" \
     --request POST \
     --url https://percy.io/api/v1/projects \
     --header 'Content-Type: application/json' \
     --data '{"data":{"attributes":{"name":"My Project","type":"web"}}}'

data^* Object

Top-level resource object for the project to create.

▶ SHOW VALUES
- attributes^* Object
  
  Attributes that define the project to create.
  
  ▶ SHOW VALUES
  - name^* String
    
    Name of the project to create.
  - type^* String
    
    Type of the project. Accepts web or app.
  - slug String
    
    Custom slug for the project. If omitted, Percy generates a slug from the name.
  - workflow String
    
    Workflow configured for the project, such as git.
  - auto-approve-branch-filter String
    
    Branch filter that specifies which branches are auto-approved.
  - ai-enabled Boolean
    
    Specifies whether AI-powered features are enabled for the project.
  - tags Array
    
    List of tags to associate with the project.
- relationships Object
  
  Relationships to associate with the project, such as a linked repository.
  
  ▶ SHOW VALUES
  - repo Object
    
    Repository relationship to link to the project.

Response attributes `201 Created` `JSON`

Response

{
  "data": {
    "type": "projects",
    "id": "4xxxxxx",
    "attributes": {
      "name": "My Project",
      "slug": "my-project",
      "type": "web",
      "full-slug": "9xxxxxxxx/my-project",
      "is-enabled": true,
      "auto-approve-branch-filter": "",
      "workflow": "git",
      "ai-enabled": false,
      "created-at": "2026-06-08T11:24:41.000Z",
      "updated-at": "2026-06-08T11:24:41.000Z"
    },
    "links": {
      "self": "/api/v1/projects/9xxxxxxxx/my-project"
    },
    "relationships": {
      "organization": {
        "links": {
          "related": "/api/v1/projects/9xxxxxxxx/my-project/organization"
        },
        "data": {
          "type": "organizations",
          "id": "30xxx"
        }
      },
      "builds": {
        "links": {
          "related": "/api/v1/builds?project_id=4xxxxxx"
        }
      },
      "tokens": {
        "links": {
          "related": "/api/v1/projects/9xxxxxxxx/my-project/tokens"
        }
      }
    }
  }
}

The 201 Created response does not return the project token. To retrieve the write token, make a follow-up request to the tokens relationship link, /api/v1/projects/<full-slug>/tokens.

attributes Object

Attributes of the created project.

▶ SHOW VALUES
- name String
  
  Name of the project.
- slug String
  
  Slug of the project.
- type String
  
  Type of the project, either web or app.
- full-slug String
  
  Full slug of the project, prefixed with the organization ID.
- is-enabled Boolean
  
  Specifies whether the project is enabled.
- auto-approve-branch-filter String
  
  Branch filter that specifies which branches are auto-approved.
- workflow String
  
  Workflow configured for the project.
- ai-enabled Boolean
  
  Specifies whether AI-powered features are enabled for the project.
- created-at String
  
  ISO-8601 time stamp when the project was created.
- updated-at String
  
  ISO-8601 time stamp when the project was last updated.
links Object

Links related to the created project.

▶ SHOW VALUES
- self String
  
  API path of the created project.
relationships Object

Relationships associated with the created project.

▶ SHOW VALUES
- organization Object
  
  Specifies details of the organization and the related API endpoint.
- repo Object
  
  Specifies details of the linked repository and the related API endpoint.
- builds Object
  
  Specifies the API endpoint to fetch builds for the project.
- tokens Object
  
  Specifies the API endpoint to fetch the project tokens, including the write token.

Update project settings

PATCH https://percy.io/api/v1/projects/{id}

Updates one or more settings on an existing Percy project. Only the attributes you include in the request body are changed. Any attribute you omit is left untouched. Use this endpoint to manage project configuration programmatically, for example to apply the same setting across many projects, sync settings from source control, or apply standard guardrails when you onboard new teams.

Note:

{id} is either the project’s full slug (org-slug/project-slug) or its numeric ID.

Find your username and access key on the BrowserStack profile page.

Project tokens are not accepted on this endpoint. Use BrowserStack Basic authentication.

The authenticated user must be a member of the project’s organization with the role admin, owner, or member, and must have the permission that gates each attribute being changed. See the Permissions section.

Permissions

Each attribute is gated by an org-level permission. If you lack any required permission, the request returns 403 and no changes are applied.

Permission	Attributes gated
`PROJECT_ARCHIVE`	`name`, `slug`, `type`, `is-enabled`
`PROJECT_SETTINGS_SCREENSHOT_LIMIT`	`screenshot-limit`
`PROJECT_SETTINGS_ALLOW_PUBLIC_VIEW`	`publicly-readable`
`PROJECT_SETTINGS_OTHER`	All other attributes and the repo relationship

Request parameters

Curl Request

curl --location --request PATCH 'https://percy.io/api/v1/projects/my-org/web-app?product=web' \
--header 'Content-Type: application/vnd.api+json' \
--header "Authorization: Basic $(echo -n '<username>:<accesskey>' | base64)" \
--data '{
    "data": {
        "type": "projects",
        "attributes": {
            "default-base-branch": "main",
            "auto-approve-branch-filter": "main release/*",
            "approval-required-branch-filter": "qa qa-*",
            "wait-for-base-build": true,
            "intelli-ignore-enabled": true,
            "intelli-ignore-diff-ignore-percentage": 0.4,
            "autofinalize": true,
            "auto-finalization-timeout-minutes": 120,
            "publicly-readable": false
        },
        "relationships": {
            "repo": { "data": { "type": "repos", "id": "12" } }
        }
    }
}'

id^* String

Project full slug (org-slug/project-slug) or numeric project ID. Path parameter.
product String

Optional query parameter. Accepts web, app, automate, or visual_scanner. Disambiguates when an org has projects of multiple products sharing the same slug.
data^* Object

Top-level request object.

▶ SHOW VALUES

Response attributes `200 OK` `JSON`

Response

{
    "data": {
        "type": "projects",
        "id": "1656",
        "attributes": {
            "name": "Web App",
            "slug": "web-app",
            "full-slug": "my-org/web-app",
            "is-enabled": true,
            "default-base-branch": "main",
            "auto-approve-branch-filter": "main release/*",
            "approval-required-branch-filter": "qa qa-*",
            "wait-for-base-build": true,
            "intelli-ignore-enabled": true,
            "intelli-ignore-diff-ignore-percentage": 0.4,
            "autofinalize": true,
            "publicly-readable": false,
            "updated-at": "2026-06-01T10:14:22.000Z"
        },
        "links": { "self": "/api/v1/projects/my-org/web-app" },
        "relationships": {
            "repo":         { "data": { "type": "repos", "id": "12" } },
            "organization": { "data": { "type": "organizations", "id": "1862" } },
            "builds":       { "links": { "related": "/api/v1/builds?project_id=1656" } },
            "tokens":       { "links": { "related": "/api/v1/projects/my-org/web-app/tokens" } }
        }
    }
}

attributes Object

The updated project attributes.

▶ SHOW VALUES
- name String
  
  Display name of the project.
- slug String
  
  URL-safe slug of the project.
- full-slug String
  
  Full slug of the project in the form org-slug/project-slug.
- is-enabled Boolean
  
  Whether the project is enabled.
- default-base-branch String
  
  Default baseline branch.
- auto-approve-branch-filter String
  
  Branch patterns that auto-approve.
- approval-required-branch-filter String
  
  Branch patterns that require explicit approval.
- wait-for-base-build Boolean
  
  Whether builds wait for a finished base build.
- intelli-ignore-enabled Boolean
  
  Whether Intelli-Ignore is enabled.
- intelli-ignore-diff-ignore-percentage Float
  
  Intelli-Ignore diff threshold from 0.0 to 1.0.
- autofinalize Boolean
  
  Whether stalled builds auto-finalize.
- publicly-readable Boolean
  
  Whether the project is publicly viewable.
- updated-at Integer
  
  Time stamp when the project was last updated.
links Object

Canonical link to the project resource.

▶ SHOW VALUES
- self String
  
  Canonical link to the project resource.
relationships Object

Links and identifiers for the project’s organization, repo, builds, tokens, and browser targets.

▶ SHOW VALUES
- repo Object
  
  The project’s linked source-code repository.
- organization Object
  
  The project’s organization.
- builds Object
  
  API endpoint to fetch the project’s builds.
- tokens Object
  
  Summary of AI analysis findings.

Did this page help you?

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Project

Get project details

Request parameters

Response attributes 200 OK JSON

attributes Object

name String

slug String

type String

full-slug String

is-enabled Boolean

diff-base String

auto-approve-branch-filter String

approval-required-branch-fitler String

default-base-branch String

updated-at Integer

publicly-readable Boolean

is-demo Boolean

is-auto-browser-upgrade Boolean

wait-for-base-build Boolean

current-period-usage Boolean

screenshot-limit Boolean

workflow Boolean

diff-sensitivity-levels Integer

visual-monitoring-urls String

latest-build-stat String

vm-last-build-baseline String

created-at Integer

links Object

self String

relationships Object

organisation Object

repo Object

builds Object

tokens Object

browser-targets Object

project-browser-targets Object

webhook-configs Object

Create a project

Request parameters

data* Object

attributes* Object

name* String

type* String

slug String

workflow String

auto-approve-branch-filter String

ai-enabled Boolean

tags Array

relationships Object

repo Object

Response attributes 201 Created JSON

attributes Object

name String

slug String

type String

full-slug String

is-enabled Boolean

auto-approve-branch-filter String

workflow String

ai-enabled Boolean

created-at String

updated-at String

links Object

self String

relationships Object

organization Object

repo Object

builds Object

tokens Object

Update project settings

Permissions

Request parameters

id* String

product String

data* Object

Response attributes 200 OK JSON

attributes Object

name String

slug String

full-slug String

Response attributes `200 OK` `JSON`

data^* Object

attributes^* Object

name^* String

type^* String

Response attributes `201 Created` `JSON`

id^* String

data^* Object

Response attributes `200 OK` `JSON`