> ## Documentation Index > Fetch the complete documentation index at: https://docs.maia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Test Execution > Trigger test execution(s) for a given project. **Scope determines which fields are required:** - `scope=TEST` — provide a `tests` array of test file names (each ending in `.test.yaml`). - `scope=PIPELINE` — provide a `pipelines` array of pipeline file names (each ending in `.orch.yaml` or `.tran.yaml`). All tests associated with those pipelines will run. - `scope=PROJECT` — runs every test in the project; no `tests` or `pipelines` field needed. `environmentName` is always required. `versionName`, `executionTag`, and `agentId` are optional and work with any scope. ## OpenAPI ````yaml /openapi/public-api-endpoint-reference.yaml post /v1/projects/{projectId}/test-executions openapi: 3.1.0 info: title: Maia Public REST API version: '1.0' servers: - description: EU1 url: https://eu1.api.matillion.com/dpc - description: US1 url: https://us1.api.matillion.com/dpc security: - bearerAuth: [] tags: - description: Manage Schedules name: Schedules - description: Manage Connections name: Connections - description: Operations for managing Project Variables name: Project Variables - description: Manage Pipelines name: Pipelines - description: Review pipelines against quality rules name: Pipeline Quality Review - description: Execute tests within a project name: Test Execution - description: Manage your AI agent tasks name: AI Agent Tasks - description: SCIM endpoints for user/group permission management name: Directory Integration - description: Publish shared pipeline artifacts name: Shared Pipeline Artifacts - description: Manage Repositories name: Repositories - description: Report on Credit Consumption name: Consumption - description: Manage Artifacts name: Artifacts - description: Operations for data lineage and governance name: Data Lineage - description: Manage Streaming Pipelines name: Streaming Pipelines - description: Execute a pipeline name: Pipeline Execution - description: '' name: Environments - description: '' name: Projects - description: Manage Agents name: Agents - description: Operations for managing Environment-level Overrides of Project Variables name: Project Variable Environment Overrides - description: Query audit events name: Audit Events - description: Connector Profiles name: Connectors paths: /v1/projects/{projectId}/test-executions: post: tags: - Test Execution summary: Create Test Execution description: >- Trigger test execution(s) for a given project. **Scope determines which fields are required:** - `scope=TEST` — provide a `tests` array of test file names (each ending in `.test.yaml`). - `scope=PIPELINE` — provide a `pipelines` array of pipeline file names (each ending in `.orch.yaml` or `.tran.yaml`). All tests associated with those pipelines will run. - `scope=PROJECT` — runs every test in the project; no `tests` or `pipelines` field needed. `environmentName` is always required. `versionName`, `executionTag`, and `agentId` are optional and work with any scope. operationId: createTestExecution parameters: - in: path name: projectId required: true schema: type: string format: uuid requestBody: content: application/json: examples: Execute All Project Tests (scope=PROJECT): description: >- Run every test in the project; no tests or pipelines field needed value: scope: PROJECT environmentName: Dev Environment Execute Specific Tests (scope=TEST): description: Run named test files; each testName must end with .test.yaml value: scope: TEST tests: - name: my-first.test.yaml - name: my-second.test.yaml environmentName: Dev Environment Execute Tests With Optional Agent: description: Target a specific agent instead of the environment default value: scope: PROJECT environmentName: Dev Environment agentId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Execute Tests With Optional Execution Tag: description: Tag the execution to control concurrency value: scope: PROJECT environmentName: Dev Environment executionTag: nightly Execute Tests With Optional Version Name: description: Pin execution to a specific artifact version value: scope: TEST tests: - name: my-first.test.yaml environmentName: Dev Environment versionName: v1.2.3 Execute Tests for Pipelines (scope=PIPELINE): description: >- Run all tests associated with the given pipelines (.orch.yaml or .tran.yaml) value: scope: PIPELINE pipelines: - name: etl-load.orch.yaml - name: transform-step.tran.yaml environmentName: Dev Environment schema: $ref: '#/components/schemas/TestExecutionRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/TestExecutionResponse' description: Test execution created '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Invalid request '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Forbidden '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unexpected error occurred '504': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Gateway timeout components: schemas: TestExecutionRequest: type: object properties: agentId: type: string description: >- Optional agent ID. If not specified, the default agent for the environment will be used example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 environmentName: type: string description: The environment to execute tests in example: environment1 maxLength: 255 minLength: 0 executionTag: type: string description: Optional tag to control execution concurrency example: nightly maxLength: 255 minLength: 0 pipelines: type: array description: >- Pipelines whose associated tests to execute (required when scope=PIPELINE) items: $ref: '#/components/schemas/PipelineReference' maxItems: 500 minItems: 0 scope: type: string description: 'Execution scope: TEST, PIPELINE, or PROJECT' enum: - TEST - PIPELINE - PROJECT example: TEST tests: type: array description: Tests to execute (required when scope=TEST) items: $ref: '#/components/schemas/TestReference' maxItems: 500 minItems: 0 versionName: type: string description: Optional artifact version name to execute tests against example: v1.2.3 maxLength: 255 minLength: 0 required: - environmentName - scope TestExecutionResponse: type: object properties: testExecutionId: type: string description: Server-generated identifier for the test execution example: 1398aa31-af57-4a6a-9752-27c2e8556c3f ProblemDetail: type: object properties: detail: type: string instance: type: string status: type: integer format: int32 title: type: string type: type: string format: uri violations: type: array items: type: string PipelineReference: type: object properties: name: type: string description: Name of the pipeline file (must end with .orch.yaml or .tran.yaml) example: mypipeline.orch.yaml minLength: 1 pattern: .*\.(orch|tran)\.yaml$ required: - name TestReference: type: object properties: name: type: string description: Name of the test file (must end with .test.yaml) example: mytest.test.yaml minLength: 1 pattern: .*\.test\.yaml$ required: - name securitySchemes: bearerAuth: bearerFormat: JWT description: a valid bearer token scheme: bearer type: http ````