---
title: "Open Petri Run"
method: POST
path: "/api/v1/runs/{id}/petri/open"
tags: ["Run Internals"]
---

# Open Petri Run

`POST /api/v1/runs/{id}/petri/open`

Opens the run in the Petri run store for the worker. `create` inserts
the run and takes its writer lease for `owner`; `write` takes the lease
of an existing run; `read` takes no lease. The lease is idempotent per
owner: a retry by the owner that holds it gets the same lease. Another
live owner is refused with `petri_run_leased`. The lease ends when the
worker releases it, when the server observes the worker exit, or by
operator release, never by timeout.

## Path parameters

- `id` string, required

## Request body

- PetriOpenRequest — An open of a Petri run for a worker.
  - `access` 'create' | 'write' | 'read', required — How a worker opens a Petri run. `create` inserts the run and takes its writer lease, `write` takes the lease of an existing run, `read` takes no lease.
  - `owner` string, nullable — The owner id the writer lease is taken for. Required for `create` and `write`, absent for `read`.

## Response `200`

Run opened

- PetriOpenResponse — A Petri run opened for a worker.
  - `locator` string, required — Where the run lives, for messages.

## Other responses

- `404` — Run not in the store (`petri_run_not_found`)
- `409` — The run exists (`petri_run_exists`, on `create`) or another live owner holds its lease (`petri_run_leased`, with the holder under `meta.owner`).

## Changes

- **2026-09-19** `efc644ab09d4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/:id/petri/open/post.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fabro-sh/apis/fabro-run-api/revisions/b760ef95cb3a?raw)