---
title: "Plan an HSX program or compiled .udl document against a build"
method: POST
path: "/v1/composer/plan"
tags: ["Start", "Founder login"]
---

# Plan an HSX program or compiled .udl document against a build

`POST /v1/composer/plan`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/composer/plan`
- Auth: HTTP bearer

Accepts HSX source text or a compiled .udl object. HSX compilation uses catalogRevisionId and the tenant overlay. The operation checks the compiled document, diffs it against the Product's current Build or an empty one, and returns every changed term with its cause, the open agreements that stay on the current Build, the deterministic complexity price and planDigest, which product.recompose takes as expectedPlanDigest. liveBlockedCapabilityIds names capabilities with no live provider admission, and unboundParties names businesses still to bind. The operation reads the build without changing it. Every successful read returns operationId and receiptId for its durable receipt.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'

## Request body

- object
  - `tenantId` string, required: Organization tenant ID
  - `catalogRevisionId` string: Immutable tenant catalog revision used when document is HSX source
  - `productId` string: Plan against this Product's current build; omit to plan a fresh composition
  - `document` union, required: An HSX program source string for server-side compilation, or a decoded .udl JSON object that is already compiled.
    - string: HSX program source text. The server compiles this exact text against the tenant's pinned catalog revision and overlay.
    - object: A .udl product definition (JSON object). Validated by the UDL grammar and semantic rules, not by this envelope.
  - `partyBindings` object, required

## Response `200`

Success

- ComposerPlanOutput
  - `operationId` string, required: Hyperscale operation ID
  - `receiptId` string, required: Hyperscale receipt ID
  - `catalogRevisionId` string, nullable, required: Immutable tenant catalog revision pinned into a Product build
  - `digest` string, required: SHA-256 of the compiled program
  - `configuration` object, required
    - `partyBindings` object, required
  - `declaredParties` object, required
  - `currentBuildDigest` string, nullable, required: The Build the plan diffs against; null for a first version
  - `changes` ProductPlanChange[], required: Every term that changes for agreements opened after the save. Running agreements keep their Build. (unresolved $ref)
  - `termChanges` ProductPlanTermChange[], required: The std terms behind changes, named as the author wrote them, such as late_forfeit 0% (std) to 50% (program). A current Build saved before terms were recorded lists its toolchain changes as UDL paths only. (unresolved $ref)
  - `exposureDelta` ComposerExposureDelta, required (unresolved $ref)
  - `toolchain` object, required
    - `current` string, nullable, required
    - `proposed` string, nullable, required
    - `attribution` 'same_toolchain' | 'recompiled' | 'old_source_failed' | 'proposed_not_current', required: recompiled: the current source was compiled again with today's toolchain, and changes from that compile carry cause toolchain. old_source_failed: it no longer compiles, so every change carries cause source.
  - `runningAgreements` integer, required: Open agreements on the current Build. They stay on it; agreements opened after saving use the new Build.
  - `planDigest` string, required: SHA-256 of the canonical plan: Build digests, document digest, changes, term changes, exposure delta, price, capabilities, live blockers and toolchain digests. Send it as expectedPlanDigest.
  - `pricing` ComposerPlanPricing, required (unresolved $ref)
  - `unboundParties` UnboundProductParty[], required: Businesses the program names with no partyBindings entry, with the attachments that use each. The Product still saves; those actions refuse with subject_party_unbound, and product.promote refuses until every business is bound (unresolved $ref)
  - `liveBlockedCapabilityIds` string[]: Capabilities in this composition with no live provider admission; present only when the composition is sandbox-only, and the reason product.promote would refuse it

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

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