Concepts
Definitions are reusable; runs record individual executions.
Scripts and workflows define the work. A run records one execution, a trigger determines when it starts, and an action provides a reusable capability during execution.
Definitions, versions and tags
Scripts and workflows share namespace/name; a name belongs to only one kind. Drafts are editable. Published versions are immutable and version numbers cannot be reused. Publishing identical content under the same version returns that version. Deprecation preserves history rather than deleting it.
References follow npm version and dist-tag conventions: docs-samples/hello@1.0.0 pins a version; @^1.2.0, @~1.2 and @1.x select ranges; @latest follows a tag. Omitting @ means @latest. Each run records the version it actually resolved.
Stable releases update latest according to version selection rules; publishing an older release does not automatically move it backwards. A prerelease requires an explicit tag such as beta. Tags such as stable and beta can move. A tag cannot be a version or range, and latest cannot be deleted. Moving a tag affects subsequent resolution without modifying published content.
Publish a version to preserve content and set a tag to point to an existing version. Tag writes do not require If-Match. Draft updates require the current ETag; publishing a draft requires expected_draft_revision.
Actions have revisions rather than semantic versions. Compatible changes take effect immediately; call records identify the revision used. Use a new action name for an incompatible schema. Published workflows lock script and child-workflow dependencies to exact versions; actions are not locked.
Run lifecycle
| Status | Meaning |
|---|---|
pending | Accepted and waiting to start. |
running | Executing. |
waiting | A workflow is waiting for an event, timer or child run. |
suspended | A workflow has been suspended. |
completed | Succeeded; read output. |
faulted | Failed; read error. |
cancelled | Cancellation completed. |
Scripts do not enter waiting or suspended. During cancellation, a run may remain running with cancel_requested_at set. A timeout is faulted with error type timeout, not a separate status. Terminal runs cannot resume. Rerun creates a new root run whose rerun_of points to the original.
HTTP success means the request was handled, not that execution succeeded. Check status, output and error. Inspect script calls and logs, or workflow tasks and waits.
Child runs and origin
A script can start a child through praxis.automation.runs.create. The child's initiator remains the original human, API Key or trigger. parent_run_id expresses the parent relationship. Filter by channel=run for runs started by another run, or by parent_run_id for a particular parent's children. Public run details expose a parent summary and root_run_id.
Cancellation cascades to children; normal parent completion allows children to continue. A child's deadline cannot exceed the parent's remaining time. Repeating a target in the call chain is rejected as a cycle. See limits for depth and fan-out bounds.
Idempotency and retries
Create a run accepts Idempotency-Key, scoped to the owner, HTTP method, path and key for 24 hours. The request fingerprint excludes wait. Reuse the key and body when retrying a network request. A replay returns the current run with Idempotent-Replayed: true. Use a fresh key when deliberately starting another execution.
A different request with the same key returns IDEMPOTENCY_KEY_MISMATCH; a request still in progress returns IDEMPOTENCY_IN_FLIGHT. See the create-run error table. Idempotency does not roll back effects from calls completed before a failure.
Cost attribution
Runs do not carry a separate execution charge. Model, search and other capabilities called during a run are charged at their regular prices and attributed to the run and trigger. A calculation that calls no such capability incurs no model or search charge.