> ## Documentation Index > Fetch the complete documentation index at: https://docs.empirical.run/llms.txt > Use this file to discover all available pages before exploring further. # Trigger a test run > Triggers a new end-to-end test run for the scoped project against the given environment, resolving the branch/build and dispatching the run. ## OpenAPI ````yaml /api-reference/openapi.generated.json put /api/test-runs openapi: 3.1.0 info: title: Empirical API version: 1.0.0 description: Programmatic access to Empirical test runs, snoozes, and more. contact: name: Empirical url: https://empirical.run servers: - url: https://api.empirical.run security: - Bearer: [] tags: - name: Test Runs description: Trigger, list, and inspect end-to-end test runs. - name: Test Cases description: >- Browse the Playwright test cases synced from a project's repository and manage their tags. - name: Environments description: >- Named deployment targets (slug + Playwright project filters) a project's tests run against. - name: Snoozes description: Temporarily suppress known test failures for specific Playwright tests. - name: Analytics description: Aggregated test-run, test-count and test-case analytics for a project. - name: Resources description: >- Project file resources — uploads stored in R2 and external link-type files (e.g. Google Sheets). - name: Badges description: Public README status badge images (SVG) for project environments. paths: /api/test-runs: put: tags: - Test Runs summary: Trigger a test run description: >- Triggers a new end-to-end test run for the scoped project against the given environment, resolving the branch/build and dispatching the run. operationId: createTestRun requestBody: content: application/json: schema: $ref: '#/components/schemas/TriggerTestRunRequest' responses: '200': description: The triggered test run. content: application/json: schema: $ref: '#/components/schemas/CreateTestRunResponse' '400': description: >- Invalid request, unknown environment, conflicting branch/build, pierre code-storage repo, or the project could not be resolved. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Project not found or not accessible. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: TriggerTestRunRequest: type: object properties: environment: type: string description: >- The environment slug to run tests against (e.g., `production`, `staging`). build: type: object properties: url: type: string description: >- URL of the deployed build being tested. Passed to tests as the `BUILD_URL` environment variable, unless `BUILD_URL` is set in `environment_variables_overrides`. branch: type: string description: Git branch name of the build. commit: type: string description: Git commit SHA of the build. commit_url: type: string description: URL to the commit (e.g., GitHub commit link). version: type: string description: Version string of the build. description: Build information to associate with the test run. metadata: type: object additionalProperties: anyOf: - type: string - type: number description: >- Custom key-value pairs to associate with the test run. Values must be strings or numbers. environment_variables_overrides: type: array items: type: object properties: name: type: string description: Name of the environment variable. value: type: string description: Value of the environment variable. required: - name - value description: Environment variables to override for this test run. tags: type: array items: type: string description: >- Tags to filter which tests to run (e.g., `@smoke`, `@critical`). Only tests matching these tags will be executed. branch: type: string description: >- Test repo branch to run. Useful for running tests from a feature branch before merging. Cannot be used together with `build` — pick one. project_id: type: integer minimum: 1 description: >- Legacy project ID; must match the request's resolved project scope when set. The project scope itself comes from the bound principal or the x-project-id header, never from the body. send_notifications: type: boolean description: Whether to send run notifications. Defaults to true. total_shards: type: integer minimum: 1 description: Override the number of shards to split the run across. rerun_source_id: type: integer minimum: 1 description: ID of the test run this run is a rerun of. rerun_only_failed: type: boolean description: When rerunning, only re-execute the previously failed tests. github_actor: type: string description: GitHub username that triggered the run, for attribution. required: - environment CreateTestRunResponse: type: object properties: data: type: object properties: trigger: type: object properties: success: type: boolean description: Whether the test run was triggered successfully. required: - success test_run: type: object properties: id: type: number description: Unique identifier for the test run. state: type: string description: Current state of the test run. test_run_branch: type: string description: Git branch being tested. created_at: type: string description: ISO 8601 timestamp when the run was created. required: - id - state - test_run_branch - created_at required: - trigger - test_run required: - data ErrorResponse: type: object properties: data: nullable: true description: Always null for error responses. error: type: object properties: message: type: string description: Human-readable error message. required: - message description: Error details. required: - data - error securitySchemes: Bearer: type: http scheme: bearer ````