---
title: "Recompile a plan"
method: POST
path: "/orgs/{orgName}/plans/{plan_id}/compile"
tags: ["Plans"]
---

# Recompile a plan

`POST /orgs/{orgName}/plans/{plan_id}/compile`

## Request

- Base URL: `https://api.signadot.com/api/v2`
- URL: `https://api.signadot.com/api/v2/orgs/{orgName}/plans/{plan_id}/compile`
- Auth: API key in header `signadot-api-key`

Re-runs LLM compilation using the source plan's prompt, creating a new plan linked to the original

## Path parameters

- `orgName` string, required
- `plan_id` string, required

## Query parameters

- `expand` 'action'

## Response `200`

OK

- RunnablePlan
  - `id` string
  - `spec` PlanSpec
    - `cluster` PlanClusterAffinity
      - `fromAnyTarget` string: FromAnyTarget names a plan param whose value is a RoutingTarget. The cluster is inferred from the variant provided at execution time (sandbox → sandbox cluster, routeGroup → RG cluster).
      - `fromCluster` string: FromCluster names a plan param whose value is a cluster name directly.
      - `fromRouteGroup` string: FromRouteGroup names a plan param whose value is a route group name. If the route group is bound to a single cluster, it resolves automatically. If the route group spans multiple clusters, the execution must specify a cluster (validated against the route group's cluster set).
      - `fromSandbox` string: FromSandbox names a plan param whose value is a sandbox name. The cluster is inferred from the sandbox's single cluster.
      - `pattern` string: Pattern is a glob pattern matched against cluster names (e.g. "prod-*", "*"). If the pattern matches exactly one connected cluster with an available runner, it is used automatically. Otherwise, the execution must specify a cluster.
    - `output` object: Output maps output names to reference expressions wiring step outputs to the plan's external interface.
    - `params` PlanField[]: Params are the external parameters the plan accepts from its caller.
      - `default` object: Default is the default value used when the field is not provided. Must conform to Schema if set.
      - `metadata` object: Metadata carries presentation hints and additional key-value pairs. Well-known keys: "contentType" (MIME type), "displayName" (UI label), "encoding" (e.g. "base64" for inlined binary values).
      - `name` string: Name is the field identifier, unique within the resource's params or outputs.
      - `required` boolean: Required indicates whether the field must be provided.
      - `schema` object: Schema is an optional JSON Schema describing the field's type and constraints.
      - `schemaRef` string: SchemaRef is an optional reference to an external schema (name, file, or URL).
    - `prompt` string: Prompt is the natural-language prompt body that was compiled to produce this plan. Empty for hand-created plans.
    - `runner` string: Runner is the plan author's preferred runner group name. If set, this runner is used directly at execution time. Conflicts with an execution-level runner.
    - `selectionHint` string: SelectionHint is a one-line agent-readable description of when to pick this plan. Surfaced on tag-list responses so an agent scanning the catalog of tagged plans can pick by purpose (analogous to how an action's Description carries "what this action does"). Free-form prose; aim for one sentence.
    - `steps` PlanStep[]: Steps are the action invocations that make up the plan's DAG.
      - `action` PlanStepAction
        - `actionID` string: ActionID is the action's ID. The only field a hand-authored plan must set on a step's action; the server hydrates the rest.
        - `body` string: Body is the action implementation (markdown with code blocks).
        - `extraInputsSchemaPolicy` PlanExtraInputsSchemaPolicy
          - `default` object: Default is the schema to apply when the plan author omitted one. Empty (nil) when this primitive is not set.
          - `require` boolean: Require, when true, makes plan compile fail if any extra_input on a step of this action is schemaless.
        - `image` PlanImageRef
          - `env` object: Env carries env entries with literal values (KEY -> literal). Applies in both paths. Reserved runner-set keys (SIGNADOT_*, HOME, TMPDIR, PATH) silently lose to the runner's values on collision.
          - `envFromInput` object: EnvFromInput carries env entries whose values resolve from a declared input at run time (KEY -> input name). Applies in both paths. Same reserved-key filtering as Env. The same KEY may not appear in both Env and EnvFromInput.
          - `inputName` string: InputName names a declared input whose value at run time is the image reference. Set when the action declared \image{ref={"input":"NAME"}}. If the input resolves to the empty string, the action runs in the runner's base image.
          - `literal` string: Literal is the image reference itself, e.g. "alpine:3.19". Set when the action declared \image{"..."} or \image{ref="..."}. An empty literal means "run in the runner's base image".
        - `name` string: Name is the action's name at the time the snapshot was taken. Display label, not the canonical identifier — ActionID is. At create time the snapshot must round-trip the registry (an explicitly supplied Name that doesn't match is rejected); at execute time the snapshot is honored as-is so renames in the registry don't break stored plans. Filled from the registry when omitted on input; otherwise preserved as supplied.
        - `outputs` PlanField[]: Outputs are the output fields parsed from the action's body.
          - `default` object: Default is the default value used when the field is not provided. Must conform to Schema if set.
          - `metadata` object: Metadata carries presentation hints and additional key-value pairs. Well-known keys: "contentType" (MIME type), "displayName" (UI label), "encoding" (e.g. "base64" for inlined binary values).
          - `name` string: Name is the field identifier, unique within the resource's params or outputs.
          - `required` boolean: Required indicates whether the field must be provided.
          - `schema` object: Schema is an optional JSON Schema describing the field's type and constraints.
          - `schemaRef` string: SchemaRef is an optional reference to an external schema (name, file, or URL).
        - `params` PlanField[]: Params are the input parameters parsed from the action's body.
          - `default` object: Default is the default value used when the field is not provided. Must conform to Schema if set.
          - `metadata` object: Metadata carries presentation hints and additional key-value pairs. Well-known keys: "contentType" (MIME type), "displayName" (UI label), "encoding" (e.g. "base64" for inlined binary values).
          - `name` string: Name is the field identifier, unique within the resource's params or outputs.
          - `required` boolean: Required indicates whether the field must be provided.
          - `schema` object: Schema is an optional JSON Schema describing the field's type and constraints.
          - `schemaRef` string: SchemaRef is an optional reference to an external schema (name, file, or URL).
        - `revision` integer: Revision is the registered action revision the snapshot was taken from. Optional on input — set to pin the step to a historical revision; otherwise the action's current revision is recorded.
        - `timeout` string: Timeout is a literal wall-clock duration string (parsed via time.ParseDuration, e.g. "60s", "5m") parsed from the top-level \timeout{"..."} directive. Empty means the system default cap applies. Mutually exclusive with TimeoutInputName.
        - `timeoutInputName` string: TimeoutInputName names a declared input whose value at run time is the duration string. Set when the action declared \timeout{{"input":"NAME"}}. Mutually exclusive with Timeout.
      - `args` PlanArgs
        - `refs` object: Refs maps param names to reference expressions (e.g. "params.cluster", "steps.foo.outputs.bar").
        - `values` object: Values maps param names to literal JSON values.
      - `condition` string: Condition is an expr-lang expression evaluated against the step's resolved args. Must evaluate to true for the step to execute.
      - `extraInputs` PlanField[]: ExtraInputs declares additional named inputs for this step beyond the action's declared params. These are wired via Args.Refs like regular params and become part of the action's eval environment.
        - `default` object: Default is the default value used when the field is not provided. Must conform to Schema if set.
        - `metadata` object: Metadata carries presentation hints and additional key-value pairs. Well-known keys: "contentType" (MIME type), "displayName" (UI label), "encoding" (e.g. "base64" for inlined binary values).
        - `name` string: Name is the field identifier, unique within the resource's params or outputs.
        - `required` boolean: Required indicates whether the field must be provided.
        - `schema` object: Schema is an optional JSON Schema describing the field's type and constraints.
        - `schemaRef` string: SchemaRef is an optional reference to an external schema (name, file, or URL).
      - `extraOutputs` PlanField[]: ExtraOutputs declares additional named outputs for this step beyond the action's declared outputs. The action writes these to ./outputs/<name> and the runner reads them back according to their schema declarations. Names must not shadow the action's declared outputs.
        - `default` object: Default is the default value used when the field is not provided. Must conform to Schema if set.
        - `metadata` object: Metadata carries presentation hints and additional key-value pairs. Well-known keys: "contentType" (MIME type), "displayName" (UI label), "encoding" (e.g. "base64" for inlined binary values).
        - `name` string: Name is the field identifier, unique within the resource's params or outputs.
        - `required` boolean: Required indicates whether the field must be provided.
        - `schema` object: Schema is an optional JSON Schema describing the field's type and constraints.
        - `schemaRef` string: SchemaRef is an optional reference to an external schema (name, file, or URL).
      - `id` string: ID is the unique identifier for this step within the plan.
      - `routingContext` PlanRoutingContext
        - `literal` RoutingTarget
          - `routeGroup` string: RouteGroup is the name of the target route group.
          - `routingKey` string: RoutingKey is the routing key used to direct traffic.
          - `sandbox` string: Sandbox is the name of the target sandbox.
        - `ref` RoutingTargetRef
          - `anyRef` string: AnyRef is a reference to a plan param whose value is a RoutingTarget (polymorphic — the caller decides sandbox, routeGroup, or routingKey).
          - `routeGroupRef` string: RouteGroupRef is a reference expression that resolves to a route group name.
          - `routingKeyRef` string: RoutingKeyRef is a reference expression that resolves to a routing key.
          - `sandboxRef` string: SandboxRef is a reference expression that resolves to a sandbox name.
  - `status` PlanStatus
    - `compiledFrom` string: CompiledFrom is the planID of the source plan, if this plan was produced by recompiling an existing plan via POST /plans/{id}/compile.
    - `createdAt` string: CreatedAt is when the plan was created. Serialized as RFC3339.
    - `createdBy` CreatedBy
      - `kind` string: Kind is "User", "ServiceAccount", or "System".
      - `name` string: Name is the user email or service-account name; empty for System.
      - `publicId` string: PublicID is the principal's public ID; empty for System.
    - `executions` integer
    - `stepDependencies` object: StepDependencies is the step dependency graph, computed from ref expressions. Keys are step IDs; values are the step IDs that step depends on.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `502`: Bad Gateway

## Changes

- **2026-05-07** `942b3992433f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/signadot/apis/signadot-api/changes/orgs/:orgName/plans/:plan_id/compile/post.md)

---

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