---
title: "Approve or replace the exact plan"
method: POST
path: "/v1/projects/{project_id}/onboarding/review"
tags: ["Onboarding"]
---

# Approve or replace the exact plan

`POST /v1/projects/{project_id}/onboarding/review`

## Request

- Base URL: `https://api.agentry.sh`
- URL: `https://api.agentry.sh/v1/projects/{project_id}/onboarding/review`
- Auth: HTTP bearer

Show the full plan to the human. Only their explicit decision approves the exact plan hash or replaces it with a fresh complete plan.

## Path parameters

- `project_id` string, required

## Headers

- `If-Match` string, required

## Request body

- union
  - object
    - `decision` 'approve', required
    - `plan_sha256` string, required
  - object
    - `decision` 'replace', required
    - `plan_sha256` string, required
    - `replacement_plan` OnboardingV3Plan, required
      - `business_question` string, required
      - `plan_markdown` string, required: Human-readable actor or interacting actors, entry, complete connected value flow, first value, business result, failures, and deploy rationale. Multi-actor products include the producer/setup side through the consumer result. Never include credentials or raw telemetry.
      - `source_snapshot` OnboardingV3SourceSnapshot, required
        - `git_head_sha` string, nullable, required
        - `source_fingerprint_sha256` string, required
        - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
      - `historical_evidence` OnboardingV3HistoricalEvidence, required
        - `status` 'historically_observed', required
        - `source` 'posthog_cloud', required
        - `posthog_project_id` integer, required
        - `observed_at` integer, required
        - `window` object, required
          - `from` integer, required
          - `to` integer, required
        - `query_receipt_sha256` string, required
        - `observations` OnboardingV3HistoricalObservation[], required: Bounded counts, timestamps, signal identifiers, and property identifiers from PostHog. This is non-authorizing historical evidence, never source proof.
          - union
            - object
              - …
            - object
              - …
      - `milestones` OnboardingV3Milestone[], required: Every material durable transition in the selected value flow.
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Durable value progress proved after this target succeeds.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `properties` string[], required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `failures` OnboardingV3Failure[], required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Business-impacting failure proved at this exact exit.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `context` string[], required
        - `safe_live_proof` boolean, required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `deploy` OnboardingV3Deploy, required
        - `environment` string, required
        - `sha_source` 'git_head', required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.

## Response `200`

Approved state or replacement planned state.

- union
  - OnboardingV3PlannedState
    - `status` 'planned', required
    - `installation_complete` false, required
    - `evidence_status` object, required
      - `historical` 'not_established' | 'historically_observed', required
      - `source` 'pending', required
    - `etag` string, required
    - `next_action` OnboardingV3PlannedNextAction, required
      - `id` 'review_exact_plan', required
      - `instruction` 'Show the bounded historical PostHog evidence, exact source-backed plan, and plan_sha256 to the human, then submit only their explicit approve or replace decision.', required
      - `requires_human` true, required
      - `operation` object, required
        - `method` 'POST', required
        - `path` string, required: Exact project-scoped operation that completes this action after its checklist.
      - `checklist` unknown[], required
        - unknown
      - `completion_condition` 'The returned state is approved for this exact plan_sha256.', required
      - `guide_anchor` 'https://github.com/agentry-sh/agentry/blob/main/INSTALL.md#4-review-and-approve-the-exact-plan', required
    - `contract_version` '3', required
    - `project_id` string, required
    - `onboarding_id` string, required
    - `revision` integer, required
    - `plan_sha256` string, required
    - `updated_at` integer, required
    - `plan` OnboardingV3Plan, required
      - `business_question` string, required
      - `plan_markdown` string, required: Human-readable actor or interacting actors, entry, complete connected value flow, first value, business result, failures, and deploy rationale. Multi-actor products include the producer/setup side through the consumer result. Never include credentials or raw telemetry.
      - `source_snapshot` OnboardingV3SourceSnapshot, required
        - `git_head_sha` string, nullable, required
        - `source_fingerprint_sha256` string, required
        - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
      - `historical_evidence` OnboardingV3HistoricalEvidence, required
        - `status` 'historically_observed', required
        - `source` 'posthog_cloud', required
        - `posthog_project_id` integer, required
        - `observed_at` integer, required
        - `window` object, required
          - `from` integer, required
          - `to` integer, required
        - `query_receipt_sha256` string, required
        - `observations` OnboardingV3HistoricalObservation[], required: Bounded counts, timestamps, signal identifiers, and property identifiers from PostHog. This is non-authorizing historical evidence, never source proof.
          - union
            - object
              - …
            - object
              - …
      - `milestones` OnboardingV3Milestone[], required: Every material durable transition in the selected value flow.
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Durable value progress proved after this target succeeds.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `properties` string[], required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `failures` OnboardingV3Failure[], required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Business-impacting failure proved at this exact exit.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `context` string[], required
        - `safe_live_proof` boolean, required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `deploy` OnboardingV3Deploy, required
        - `environment` string, required
        - `sha_source` 'git_head', required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
  - OnboardingV3ApprovedState
    - `status` 'approved', required
    - `installation_complete` false, required
    - `evidence_status` object, required
      - `historical` 'not_established' | 'historically_observed', required
      - `source` 'pending', required
    - `etag` string, required
    - `next_action` OnboardingV3ApprovedNextAction, required
      - `id` 'instrument_and_start_proof', required
      - `instruction` 'Implement the approved plan through the customer's existing official PostHog SDKs, test it, commit a clean tree, capture the final source snapshot, then start proof.', required
      - `requires_human` false, required
      - `operation` object, required
        - `method` 'POST', required
        - `path` string, required: Exact project-scoped operation that completes this action after its checklist.
      - `checklist` unknown[], required
        - unknown
      - `completion_condition` 'The returned state is proving and fresh runtime and CI proof markers were received.', required
      - `guide_anchor` 'https://github.com/agentry-sh/agentry/blob/main/INSTALL.md#5-apply-approved-telemetry-changes-directly-to-posthog', required
    - `contract_version` '3', required
    - `project_id` string, required
    - `onboarding_id` string, required
    - `revision` integer, required
    - `plan_sha256` string, required
    - `updated_at` integer, required
    - `approved_at` integer, required
    - `plan` OnboardingV3Plan, required
      - `business_question` string, required
      - `plan_markdown` string, required: Human-readable actor or interacting actors, entry, complete connected value flow, first value, business result, failures, and deploy rationale. Multi-actor products include the producer/setup side through the consumer result. Never include credentials or raw telemetry.
      - `source_snapshot` OnboardingV3SourceSnapshot, required
        - `git_head_sha` string, nullable, required
        - `source_fingerprint_sha256` string, required
        - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
      - `historical_evidence` OnboardingV3HistoricalEvidence, required
        - `status` 'historically_observed', required
        - `source` 'posthog_cloud', required
        - `posthog_project_id` integer, required
        - `observed_at` integer, required
        - `window` object, required
          - `from` integer, required
          - `to` integer, required
        - `query_receipt_sha256` string, required
        - `observations` OnboardingV3HistoricalObservation[], required: Bounded counts, timestamps, signal identifiers, and property identifiers from PostHog. This is non-authorizing historical evidence, never source proof.
          - union
            - object
              - …
            - object
              - …
      - `milestones` OnboardingV3Milestone[], required: Every material durable transition in the selected value flow.
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Durable value progress proved after this target succeeds.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `properties` string[], required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `failures` OnboardingV3Failure[], required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Business-impacting failure proved at this exact exit.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `context` string[], required
        - `safe_live_proof` boolean, required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `deploy` OnboardingV3Deploy, required
        - `environment` string, required
        - `sha_source` 'git_head', required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
  - OnboardingV3ProvingState
    - `status` 'proving', required
    - `installation_complete` false, required
    - `evidence_status` object, required
      - `historical` 'not_established' | 'historically_observed', required
      - `source` 'pending', required
    - `etag` string, required
    - `next_action` OnboardingV3ProvingNextAction, required
      - `id` 'exercise_and_verify', required
      - `instruction` 'Deploy the approved final source with the CI marker, then exercise every approved real milestone and safe error with the short-lived PostHog proof property, then verify.', required
      - `requires_human` false, required
      - `operation` object, required
        - `method` 'POST', required
        - `path` string, required: Exact project-scoped operation that completes this action after its checklist.
      - `checklist` unknown[], required
        - unknown
      - `completion_condition` 'The returned state has evidence_status.source source_verified, installation_complete true, and next_action null.', required
      - `guide_anchor` 'https://github.com/agentry-sh/agentry/blob/main/INSTALL.md#6-prove-the-deployed-result', required
    - `contract_version` '3', required
    - `project_id` string, required
    - `onboarding_id` string, required
    - `revision` integer, required
    - `plan_sha256` string, required
    - `updated_at` integer, required
    - `implementation_source_snapshot` OnboardingV3SourceSnapshot, required
      - `git_head_sha` string, nullable, required
      - `source_fingerprint_sha256` string, required
      - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
    - `proof_session` object, required
      - `proof_session_id` string, required
      - `status` 'open', required
      - `started_at` integer, required
      - `expires_at` integer, required
    - `plan` OnboardingV3Plan, required
      - `business_question` string, required
      - `plan_markdown` string, required: Human-readable actor or interacting actors, entry, complete connected value flow, first value, business result, failures, and deploy rationale. Multi-actor products include the producer/setup side through the consumer result. Never include credentials or raw telemetry.
      - `source_snapshot` OnboardingV3SourceSnapshot, required
        - `git_head_sha` string, nullable, required
        - `source_fingerprint_sha256` string, required
        - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
      - `historical_evidence` OnboardingV3HistoricalEvidence, required
        - `status` 'historically_observed', required
        - `source` 'posthog_cloud', required
        - `posthog_project_id` integer, required
        - `observed_at` integer, required
        - `window` object, required
          - `from` integer, required
          - `to` integer, required
        - `query_receipt_sha256` string, required
        - `observations` OnboardingV3HistoricalObservation[], required: Bounded counts, timestamps, signal identifiers, and property identifiers from PostHog. This is non-authorizing historical evidence, never source proof.
          - union
            - object
              - …
            - object
              - …
      - `milestones` OnboardingV3Milestone[], required: Every material durable transition in the selected value flow.
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Durable value progress proved after this target succeeds.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `properties` string[], required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `failures` OnboardingV3Failure[], required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Business-impacting failure proved at this exact exit.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `context` string[], required
        - `safe_live_proof` boolean, required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `deploy` OnboardingV3Deploy, required
        - `environment` string, required
        - `sha_source` 'git_head', required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
  - OnboardingV3VerifiedState
    - `status` 'verified', required
    - `installation_complete` true, required
    - `evidence_status` object, required
      - `historical` 'not_established' | 'historically_observed', required
      - `source` 'source_verified', required
    - `etag` string, required
    - `next_action` unknown, required
    - `contract_version` '3', required
    - `project_id` string, required
    - `onboarding_id` string, required
    - `revision` integer, required
    - `plan_sha256` string, required
    - `updated_at` integer, required
    - `implementation_source_snapshot` OnboardingV3SourceSnapshot, required
      - `git_head_sha` string, nullable, required
      - `source_fingerprint_sha256` string, required
      - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
    - `proof_session` object, required
      - `proof_session_id` string, required
      - `status` 'satisfied', required
      - `started_at` integer, required
      - `expires_at` integer, required
    - `receipt` OnboardingV3VerifiedReceipt, required
      - `evidence_status` 'source_verified', required
      - `source_verified_at` integer, required
      - `analytics` OnboardingV3ObservedMilestone[], required
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `required_properties` string[], required
        - `observed_properties` string[], required
        - `row_count` integer, required
      - `error` object, required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `required_context` string[], required
        - `observed_context` string[], required
        - `row_count` integer, required
      - `deploy` object, required
        - `environment` string, required
        - `source_snapshot` OnboardingV3SourceSnapshot, required
          - `git_head_sha` string, nullable, required
          - `source_fingerprint_sha256` string, required
          - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
        - `row_count` integer, required
    - `plan` OnboardingV3Plan, required
      - `business_question` string, required
      - `plan_markdown` string, required: Human-readable actor or interacting actors, entry, complete connected value flow, first value, business result, failures, and deploy rationale. Multi-actor products include the producer/setup side through the consumer result. Never include credentials or raw telemetry.
      - `source_snapshot` OnboardingV3SourceSnapshot, required
        - `git_head_sha` string, nullable, required
        - `source_fingerprint_sha256` string, required
        - `source_fingerprint_algorithm` 'agentry-source-tree-sha256-v1', required
      - `historical_evidence` OnboardingV3HistoricalEvidence, required
        - `status` 'historically_observed', required
        - `source` 'posthog_cloud', required
        - `posthog_project_id` integer, required
        - `observed_at` integer, required
        - `window` object, required
          - `from` integer, required
          - `to` integer, required
        - `query_receipt_sha256` string, required
        - `observations` OnboardingV3HistoricalObservation[], required: Bounded counts, timestamps, signal identifiers, and property identifiers from PostHog. This is non-authorizing historical evidence, never source proof.
          - union
            - object
              - …
            - object
              - …
      - `milestones` OnboardingV3Milestone[], required: Every material durable transition in the selected value flow.
        - `event` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Durable value progress proved after this target succeeds.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `properties` string[], required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `failures` OnboardingV3Failure[], required
        - `marker` string, required: Repository-chosen opaque value; spelling is not an acceptance signal.
        - `meaning` string, required: Business-impacting failure proved at this exact exit.
        - `posthog_boundary` 'browser_posthog' | 'server_posthog', required
        - `context` string[], required
        - `safe_live_proof` boolean, required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.
      - `deploy` OnboardingV3Deploy, required
        - `environment` string, required
        - `sha_source` 'git_head', required
        - `targets` OnboardingV3SourceTarget[], required
          - `file` string, required: Repository-relative shipped source or configuration path.
          - `anchor` string, required: Exact source text locating the outcome boundary in this file.

## Other responses

- `default`: Agent-readable failure with a stable code and recovery action.

---

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