hog_flows

Agent-authored changes to this workflow, awaiting a human's decision.

Creating one stages nothing: a proposal only reaches the workflow's draft once a human approves it, and only reaches the live config once someone publishes that draft.

post/api/projects/{project_id}/hog_flows/{id}/proposals/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/hog_flows/{id}/proposals/
  • Auth: HTTP bearer

Path parameters

idstring uuid required

A UUID string identifying this hog flow.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

titlestring required

Short summary of the proposed change.

rationalestring required

Why this change is worth making, in prose a human reads.

contentobject required

Only the workflow content fields this proposal changes. Approving merges them over the live content to build the staged draft, so unrelated parts of the workflow stay as they are. In actions, send each step you change with its id and only the fields you change; they merge into the live step, and a null field deletes it.

evidenceobject

The metric numbers behind the proposal, so a human can judge it without re-deriving them.

base_versioninteger required

Workflow version this was authored against, as read from the workflow. It is the snapshot approve compares against to tell whether someone edited the same steps or fields since, and a defaulted version would read as current however long the producer took.

step_idstring nullable

The step this is about. Send it for a change to one step: both the evidence and the outcome then read that step's metrics, so a change to one email in a sequence is not measured against the rest. Leave it out only for a change that spans the workflow, such as its exit condition or a step being taken out, which is measured on the workflow's own numbers.

source_idstring nullable

Stable id of the producing agent run or finding. Posting the same one twice returns the existing proposal instead of creating a duplicate.

Response

idstring uuid required
titlestring required

Short summary of the proposed change.

rationalestring required

Why the producer thinks this change is worth making.

contentobject required

Only the content fields the proposal changes. Valid keys: actions, edges, trigger_masking, conversion, exit_condition, email_sending_rate_limit, variables. Each value has the same shape as on the workflow itself.

evidenceobject required

The numbers behind the proposal, read back by name. Five keys are required: metric, the metric name; current_value, its value as a number (a rate as a fraction, 0.0865, never a string); unit, either rate or count, since 1.0 is either every message or one of them; n, the denominator that value was computed over; and guardrails, a list of {metric, value, n, unit} counter-metrics read over the same window, empty only if none apply. PostHog then reads the step's own metrics at base_version when the suggestion is filed and stores them under measured; the page shows that reading and flags a disagreement with yours. Also conventional: target_value, window, query, app_source_id. A rate with no denominator lets a reviewer mistake noise for a result, a target with no counter-metrics hides a change that lifts one number by harming another, and a number under a key of your own reads to a person as no evidence at all.

step_idstring nullable required

The workflow step this is about. Set for a change to one step: the evidence and the outcome then read that step's metrics, so a change to one email in a sequence is not measured against the rest. Null only for a change that spans the workflow, such as its exit condition or a step being taken out, which is measured on the workflow's own numbers.

base_versioninteger required

Live workflow version this was authored against. Approving compares the steps and fields this changes against that version to tell whether somebody else already changed them.

is_staleboolean required

Whether approving this would undo an edit made since it was proposed. False while the workflow only changed elsewhere, because approving merges only what the proposal changes.

status'suggested' | 'approved' | 'rejected' | 'applied' required
  • suggested - Suggested
  • approved - Approved
  • rejected - Rejected
  • applied - Applied
source_idstring nullable required

Stable id of the producing agent run or finding, e.g. 'run:<run id>:finding:<finding id>'.

created_atstring date-time required
resolved_atstring date-time nullable required
applied_versioninteger nullable required

Workflow version the approved change went live as.

rejection_reasonstring required

Why the person who rejected this suggestion rejected it, or empty when they gave no reason.

Changes

No recorded changes to this operation across all 1 revision of this API.