> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start Test Run > Start a test run: replay this workspace's test cases against the draft (or a published version) and check the draft's row-level security. Returns a job id to poll with `get`. ## OpenAPI ````yaml post /v2/api/projects/{projectId}/workspaces/{workspaceId}/test-runs openapi: 3.1.0 info: title: Upsolve API version: 1.5.0 servers: - url: https://api.upsolve.ai security: [] tags: [] paths: /v2/api/projects/{projectId}/workspaces/{workspaceId}/test-runs: post: summary: 'Start a test run: replay this workspace''s test ca…' description: >- Start a test run: replay this workspace's test cases against the draft (or a published version) and check the draft's row-level security. Returns a job id to poll with `get`. operationId: PostV2ApiProjectsProjectIdWorkspacesWorkspaceIdTestRuns parameters: - name: projectId in: path required: true description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/test-runs Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ - name: workspaceId in: path required: true description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/test-runs Parameter schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ requestBody: description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/test-runs Request body content: application/json: schema: type: object properties: apiKey: type: string minLength: 1 description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. examples: - up_embed_************ organizationId: description: >- Your Upsolve organization's UUID — the org that owns the API key and project. This is NOT a project organization: do not pass a value registered via /projects/register-organization, and do not pass an `externalId` (only `projectOrganizationId` accepts those). Omit it when using an org-bound API key — the org is read from the key and any value sent here is ignored. Required only for user-scoped API keys (created under Account → Developer settings) and for the Supabase JWT path, where the org is ambiguous and membership is verified against it. examples: - 123e4567-e89b-12d3-a456-426614174000 type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ version: default: draft description: >- Which version to test: 'draft' (the default) for the unpublished working copy, or a published version number. A run on a published version never satisfies the publish gate. anyOf: - type: string const: draft - type: integer minimum: 1 maximum: 9007199254740991 caseIds: description: >- Run only these test cases. Omit to run them all. A narrowed run never satisfies the publish gate. type: array items: type: string projectUserId: description: >- Answer as this project user instead of yourself: their row-level security applies, and their environment decides which database the cases run against. Omit to run as your own project user (production). type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ environment: description: >- The environment this run must read. Refused (409 TEST_USER_WRONG_ENVIRONMENT) when the project user it answers as is in another environment; without projectUserId you answer as yourself, in production. Omit to run in whichever environment that user is in. type: string required: [] examples: example1: value: apiKey: up_embed_************ organizationId: 123e4567-e89b-12d3-a456-426614174000 responses: '201': description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/test-runs Positive response content: application/json: schema: type: object properties: status: type: string const: success data: type: object properties: jobId: type: string status: type: string enum: - pending - processing - completed - failed - cancelled reused: type: boolean description: >- True when this joined a run that was already in flight. totalCases: type: number required: - jobId - status - reused - totalCases additionalProperties: false required: - status - data additionalProperties: false '400': description: >- POST /v2/api/projects/:projectId/workspaces/:workspaceId/test-runs Negative response content: application/json: schema: type: object properties: status: type: string const: error error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false required: - status - error additionalProperties: false security: - APIKEY_1: [] components: securitySchemes: APIKEY_1: type: apiKey in: query name: apiKey x-in-actual: body description: apiKey MUST be supplied within the request body instead of query ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.