# Launch Pipeline Run

`POST /v1/runs`

Launch any launchable template with flat values for its exposed ports.

A template billed per run reserves its whole bound before it starts and
needs ``max_cost``; ``POST /v1/runs/estimate`` gives the bound first.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Request body

Required: `application/json` `RunSubmitRequest`

## Responses

- `200` Successful Response: `application/json` `RunSubmitResponse`
- `400` Values violate the template contract: `application/json` `ErrorResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `402` The account cannot cover the run's bound
- `403` Missing capability on the workspace: `application/json` `ErrorResponse`
- `409` Stale quote, or an idempotency key reused
- `422` Validation error, or the run's bound is over max_cost

## Schemas

```yaml
RunSubmitRequest:
  properties:
    pipeline_template_id:
      type: string
      format: uuid
    project_id:
      type: string
      format: uuid
    values:
      additionalProperties: true
      type: object
    name:
      maxLength: 255
      type:
        - string
        - "null"
    max_cost:
      minimum: 1
      type:
        - integer
        - "null"
    sample_cap:
      minimum: 1
      type:
        - integer
        - "null"
    idempotency_key:
      maxLength: 200
      minLength: 1
      type:
        - string
        - "null"
    quote_digest:
      pattern: ^[0-9a-f]{64}$
      type:
        - string
        - "null"
  additionalProperties: false
  type: object
  required:
    - pipeline_template_id
    - project_id
  title: RunSubmitRequest
RunSubmitResponse:
  properties:
    job_id:
      type: string
    status:
      type: string
    message:
      type: string
    audience:
      nullable: true
      type: string
      enum:
        - internal
        - public
  type: object
  required:
    - job_id
    - status
    - message
  title: RunSubmitResponse
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
```