---
title: "Acknowledge an external-machine command"
method: POST
path: "/v1/machines/{machine_id}/commands/{command_id}/results"
tags: ["machines"]
---

# Acknowledge an external-machine command

`POST /v1/machines/{machine_id}/commands/{command_id}/results`

## Request

- Base URL: `https://coasty.ai`
- URL: `https://coasty.ai/v1/machines/{machine_id}/commands/{command_id}/results`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/coasty/apis/coasty-public-api/docs/v1/machines/:machine_id/commands/:command_id/results/post.ts> (a function with typed inputs; its response is checked against the schema)

DEVICE TOKEN ONLY. Submit a terminal success/failure using the exact fencing_token and precondition_frame_id from the command. The optional observation atomically supplies the post-action frame. An identical result replay returns replayed=true; a different body for a completed command, a frame-precondition mismatch, an expired command, or a stale fencing token returns 409 and is never re-executed.

## Request body

- ExternalMachineCommandResultRequest
  - `fencing_token` integer, required
  - `precondition_frame_id` string, uuid, nullable, required: Must exactly echo the command envelope's precondition_frame_id, including null. A mismatch is 409 FRAME_PRECONDITION_MISMATCH.
  - `success` boolean, required
  - `result` object, nullable
  - `error` string, nullable
  - `observation` object, nullable: Optional post-action frame, atomically accepted with the command result.
    - `sequence` integer, required
    - `media_type` 'image/png' | 'image/jpeg', required
    - `screenshot` union, required: One static PNG/JPEG screenshot as raw base64 or an exact data:image/png;base64 / data:image/jpeg;base64 URI. Animated and multi-frame images are rejected. This per-image limit does not multiply the ordinary 15 MiB aggregate JSON request-body cap.
      - string
      - string
      - string
    - `sha256` string, nullable: Optional SHA-256 of the submitted decoded image bytes, before metadata stripping and server normalization.
    - `width` integer, nullable
    - `height` integer, nullable: width and height must be supplied together when either is present.

## Response `200`

Command result accepted or safely replayed.

- ExternalMachineCommandResultResponse
  - `machine_id` string, required
  - `command_id` string, uuid, required
  - `status` 'completed' | 'failed', required
  - `replayed` boolean, required: true for a byte-equivalent result replay; a conflicting result returns 409.
  - `request_id` string, required

## Other responses

- `400`: Invalid request body or parameters.
- `401`: Missing, malformed, revoked, or machine-mismatched external device token. Pass the one-time machine token as `Authorization: Bearer <device_token>`; owner API keys are not accepted on device-plane routes. Revoked tokens may return DEVICE_REVOKED.
- `403`: API key lacks the required scope or tier-feature is unavailable on the caller's plan.
- `404`: Resource not found in this key's namespace.
- `409`: The resource state conflicts with this operation.
- `413`: The request body exceeds the endpoint limit.
- `422`: The JSON shape is valid but one or more values violate the endpoint contract.
- `429`: Rate or concurrency limit exceeded.
- `500`: Unexpected server error. Retry with exponential backoff.
- `502`: An upstream dependency returned an invalid response.
- `503`: A required service is temporarily unavailable.
- `504`: An upstream dependency timed out.

---

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