Apply

Plan a v2 deploy

Plan a release. Returns the agent-deploy-observability v2 plan envelope: plan_id, operation_id, gateway-computed manifest_digest, missing_content, top-level resource diff buckets, expected_events, warnings, and optional payment_required. Body limit 5 MB; bytes go direct-to-S3. Body mode=reviewed_plan creates a short-lived require-able reviewed plan with plan_fingerprint/plan_expires_at and operation_id=null. Body required_plan verifies a reviewed plan before upload. Legacy ?dry_run=true computes the same envelope without creating plan or operation rows and is not require-able.

post/apply/v1/plans

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/apply/v1/plans
  • Auth: API key in header SIGN-IN-WITH-X

Query parameters

dry_runboolean

When true, validate and diff the inline spec without creating deploy_plans/deploy_operations rows. Cannot be combined with manifest_ref.

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Request body

idempotency_keystring
mode'reviewed_plan'

Create a short-lived, require-able reviewed plan. Distinct from legacy ?dry_run=true, which creates no plan row.

Example request

{
  "spec": {
    "base": {
      "release_id": "rel_1741340000_abcd1234"
    },
    "database": {
      "migrations": [
        {
          "checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "sql_ref": {
            "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
          }
        }
      ]
    },
    "site": {
      "replace": {
        "index.html": {
          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "size": 1234,
          "content_type": "text/html"
        }
      }
    },
    "routes": {
      "replace": [
        {
          "pattern": "/admin",
          "methods": [
            "GET"
          ],
          "target": {
            "type": "function",
            "name": "admin"
          }
        },
        {
          "pattern": "/admin/*",
          "target": {
            "type": "function",
            "name": "admin"
          }
        },
        {
          "pattern": "/events",
          "methods": [
            "GET"
          ],
          "target": {
            "type": "static",
            "file": "events.html"
          }
        }
      ]
    },
    "project_id": "prj_1741340000_0042"
  },
  "manifest_ref": {
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

Response

Plan created, reviewed plan created, required-plan preflight verified, or legacy dry-run computed. Reviewed plans return plan_fingerprint/plan_expires_at and operation_id as null; legacy dry-run returns plan_id and operation_id as null. On a project with a vault_policy the response carries a vault rider; when the policy is required it also carries a vault_push next_action with the exact capture_binding values.

kind'plan_response' required
schema_version'agent-deploy-observability.v1' required
plan_idstring nullable required

Null only for legacy ?dry_run=true. Reviewed-plan mode returns a non-null require-able plan id.

operation_idstring nullable required

Null for legacy ?dry_run=true and reviewed-plan mode. Ordinary apply plans create an operation id.

base_release_idstring nullable required
manifest_digeststring required
is_noopboolean required
summarystring required

Pre-rendered counts in prose. User identifiers live in warnings[].affected.

expected_eventsstring[] required

Operation event types expected during commit, in execution order.

plan_fingerprintstring nullable

Versioned fingerprint binding reviewed intent: normalized spec digest, manifest digest, concrete base identity, planner semantics, confirmation-required warnings, destructive sets, and diff identity. Present for reviewed-plan mode.

plan_expires_atstring date-time nullable

Reviewed plan expiration timestamp. Present for reviewed-plan mode; current TTL is one hour.

planner_semantics_versionstring nullable

Planner semantics version bound into plan_fingerprint.

base_identitystring nullable

Concrete base identity bound into plan_fingerprint, e.g. empty or release:<release_id>.

next_actionsobject[]

Structured recovery/apply actions. CLI actions include command and argv; direct HTTP callers can branch on type/path/method fields when present.

Example response

{
  "plan_id": "plan_1741340000_abcd1234",
  "operation_id": "op_1741340000_abcd1234",
  "manifest_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "warnings": [
    {
      "code": "MISSING_REQUIRED_SECRET"
    }
  ],
  "missing_content": [
    {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ],
  "payment_required": {
    "asset": "USDC",
    "reason": "lease_renewal"
  },
  "rehearsal": {
    "rehearse_url": "/apply/v1/plans/plan_1741340000_abcd1234/rehearse",
    "next_actions": [
      {
        "type": "commit_plan",
        "command": "POST /apply/v1/plans/plan_1741340000_abcd1234/commit"
      }
    ]
  },
  "migrations": {
    "new": [
      {
        "checksum_hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ],
    "noop": [
      {
        "checksum_hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ]
  },
  "site": {
    "added": [
      {
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ],
    "changed": [
      {
        "sha256_old": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "sha256_new": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ]
  },
  "routes": {
    "added": [
      {
        "pricing": {
          "mode": "always",
          "amount_usd_micros": 250000,
          "pay_to": "org_default_payout"
        }
      }
    ],
    "removed": [
      {
        "pricing": {
          "mode": "always",
          "amount_usd_micros": 250000,
          "pay_to": "org_default_payout"
        }
      }
    ],
    "changed": [
      {
        "from": {
          "pricing": {
            "mode": "always",
            "amount_usd_micros": 250000,
            "pay_to": "org_default_payout"
          }
        },
        "to": {
          "pricing": {
            "mode": "always",
            "amount_usd_micros": 250000,
            "pay_to": "org_default_payout"
          }
        }
      }
    ]
  },
  "static_assets": {
    "legacy_immutable_warnings": [
      {
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ],
    "previous_immutable_failures": [
      {
        "previous_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "candidate_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    ]
  }
}

Changes

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