---
title: "Trigger a run (sync for rules/assisted; External parks at awaiting_decision)"
method: POST
path: "/v1/apps/{id}/runs"
tags: ["Apps"]
---

# Trigger a run (sync for rules/assisted; External parks at awaiting_decision)

`POST /v1/apps/{id}/runs`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/apps/{id}/runs`
- Auth: HTTP bearer

Idempotent per (app, Idempotency-Key). dry_run produces a full trace and provably no side effects.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `dry_run` 'true'

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `input` object
  - `idempotency_key` string
  - `dry_run` boolean

## Response `200`

The run (projection shape).

- AppRun: Run projection. The journal (/events) and the sealed record (/record) are the ledger.
  - `run_id` string, uuid
  - `app` string: slug@vN
  - `status` 'pending' | 'assembling' | 'awaiting_decision' | 'deciding' | 'verifying' | 'executing' | 'completed' | 'failed' | 'held' | 'cancelled'
  - `mode` string
  - `dry_run` boolean
  - `trigger` object
  - `decision` object, nullable
  - `decided_by` object, nullable: Actor union — rules / hosted_agent / human / external_agent recorded identically.
  - `thresholds_applied` string[]
  - `reviews` string[]
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable

## Other responses

- `409`: The request conflicts with the current resource state.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)