---
title: "Submit a Forma command"
method: POST
path: "/commands"
tags: ["commands"]
---

# Submit a Forma command

`POST /commands`

Submits a Forma command to the agent. The command is executed asynchronously.

## Headers

- `Client-ID` string, required

## Response `200`

OK: No changes required, or simulation result returned.

- ModelSubmitCommandResponse
  - `CommandId` string
  - `Description` GithubComPlatformEngineeringLabsFormaePkgApiModelDescription
    - `Confirm` boolean
    - `Text` string
  - `Simulation` ModelSimulation
    - `ChangesRequired` boolean
    - `Command` GithubComPlatformEngineeringLabsFormaePkgApiModelCommand
      - `Command` string
      - `CommandId` string
      - `EndTs` string
      - `PolicyUpdates` ModelPolicyUpdate[]
        - `Duration` integer — milliseconds
        - `ErrorMessage` string
        - `ModifiedTs` string
        - `OldPolicyConfig` integer[] — Previous policy configuration (for updates)
        - `Operation` string
        - `PolicyConfig` integer[] — Current policy configuration
        - `PolicyLabel` string
        - `PolicyType` string — "ttl", etc.
        - `ReferencingStacks` string[] — For skip operations - stacks still referencing this policy
        - `StackLabel` string
        - `StartTs` string
        - `State` string
      - `ResourceUpdates` ModelResourceUpdate[]
        - `CascadeSource` string
        - `CreateOnlyPatch` integer[] — CreateOnlyPatch is a JSON-patch document (same format as PatchDocument) listing only the ops against createOnly fields that triggered a resource replacement. Populated on the delete half of a replace pair so the CLI can render which immutable properties forced the replace. Never sent to resource plugins — the replace executes as a plain destroy + create.
        - `CurrentAttempt` integer
        - `Duration` integer — milliseconds
        - `ErrorMessage` string
        - `GroupId` string
        - `IsCascade` boolean
        - `MaxAttempts` integer
        - `NativeId` string
        - `OldLabel` string — OldLabel is the resource's previous label. Populated only when a label rename is part of this update (RFC-0041 alias path); empty otherwise. The renderer uses it to surface the rename to the user.
        - `OldProperties` integer[]
        - `OldStackName` string
        - `Operation` string
        - `PatchDocument` integer[]
        - `Properties` integer[]
        - `ReferenceLabels` object
        - `ResourceId` string
        - `ResourceLabel` string
        - `ResourceType` string
        - `StackName` string
        - `State` string
        - `StateMessage` string
      - `StackUpdates` ModelStackUpdate[]
        - `Description` string
        - `Duration` integer — milliseconds
        - `ErrorMessage` string
        - `ModifiedTs` string
        - `Operation` string
        - `StackLabel` string
        - `StartTs` string
        - `State` string
      - `StartTs` string
      - `State` string
      - `TargetUpdates` ModelTargetUpdate[]
        - `CascadeSource` string
        - `DesiredConfig` integer[]
        - `Discoverable` boolean
        - `Duration` integer — milliseconds
        - `ErrorMessage` string
        - `ExistingConfig` integer[]
        - `IsCascade` boolean
        - `ModifiedTs` string
        - `Operation` string
        - `StartTs` string
        - `State` string
        - `TargetLabel` string
    - `Warnings` string[]

## Other responses

- `202` — Accepted: The command is validated, stored, and queued for execution.
- `500` — Internal Server Error.

---

[API](https://skmtc.net/platform-engineering-labs/apis/formae-rest-api.md) · [All operations](https://skmtc.net/platform-engineering-labs/apis/formae-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/platform-engineering-labs/formae-rest-api/versions/e4ee5fb76a4f/schema)