---
title: "Request runs for test cases"
method: POST
path: "/v1/missions/submit"
tags: ["missions"]
---

# Request runs for test cases

`POST /v1/missions/submit`

## Request

- Base URL: `https://api.qualgent.ai`
- URL: `https://api.qualgent.ai/v1/missions/submit`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/qualgent/apis/qualgent-api-service/docs/v1/missions/submit/post.ts> (a function with typed inputs; its response is checked against the schema)

Request runs for one or more test cases against an app build. This is the same
    flow as the Run button in the QualGent dashboard: the request is recorded as a
    submission, each test case is dispatched for testing, and results are reviewed
    by QualGent before they are published to you.

    **App build:**
    - `app_file_id` is optional. If omitted, your organization's latest uploaded app is used.
    - If you have no app and `app_install_source` is not `store_listing`, this returns `404`.

    **One open request at a time:**
    - An organization can have one open request. While one is open this returns `409`
      with `code: "run_in_progress"` and the open request in `open_run`.
    - Send `replace_open: true` to cancel and remove the open request and start this one.

    **Partial failures:**
    - A test case that cannot be submitted is listed in `failures`; the others still go ahead.
      The response is `200` either way, so check `failed`.

    **Returns:**
    - `submission_id` to follow progress with `GET /v1/missions/submissions?submission_id=...`

    **Retries:**
    - If this returns `504`, the request may still have been created. Check
      `GET /v1/missions/submissions` before sending it again.

## Headers

- `x-api-key` string

## Request body

- MissionSubmitRequest: Request runs for one or more test cases against an app build
  - `test_case_ids` string[], required: IDs of the test cases to run. Duplicates are ignored.
  - `app_file_id` string, nullable: ID of the app build to test, as returned by POST /v1/apps/upload. Defaults to your organization's latest uploaded app. Not needed when app_install_source is 'store_listing'.
  - `app_install_source` 'uploaded_app' | 'store_listing', nullable: How the build is installed. Defaults to 'uploaded_app'.
  - `vars` object, nullable: Values for the test case's declared variables. Only accepted when exactly one test case is requested.
  - `replace_open` boolean, nullable: An organization has one open request at a time. Set to true to cancel and remove the open request and start this one; otherwise a 409 is returned while one is open.

## Response `200`

Request submitted

- MissionSubmitResponse: Response after submitting a request
  - `submitted` integer, required: Number of test cases submitted
  - `failed` integer, required: Number of test cases that could not be submitted
  - `failures` MissionSubmitFailure[]: One entry per failed test case
    - `test_case_id` string, required: Test case ID
    - `error` string, required: Why it was not submitted
  - `submission_id` string, nullable: ID of the request. Pass it to GET /v1/missions/submissions to follow progress.

## Other responses

- `400`: Bad request - invalid body
- `401`: Invalid or missing API key
- `403`: Your plan or role does not allow requesting runs
- `404`: App build not found, or no app uploaded and `app_file_id` omitted
- `409`: A request is already open for your organization
- `422`: Validation Error
- `502`: Upstream service error
- `504`: Timed out before the request was confirmed

## Changes

- **2026-10-07** `659dfde2d76c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/qualgent/apis/qualgent-api-service/changes/v1/missions/submit/post.md)

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) - [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/qualgent/apis/qualgent-api-service/revisions/e04a6e95240e?raw)