> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Recording Command

> Cancel a pending recording command

Cancel a pending command. Only commands with `pending` status can be cancelled.

## Authentication

Requires an [API key](/authentication) with `devices:write` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.bota.dev/v1/devices/dev_abc123/commands/cmd_xyz789 \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.bota.dev/v1/devices/dev_abc123/commands/cmd_xyz789',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer sk_live_...',
      },
    }
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://api.bota.dev/v1/devices/dev_abc123/commands/cmd_xyz789',
      headers={'Authorization': 'Bearer sk_live_...'},
  )
  ```
</RequestExample>

## Path Parameters

<ParamField path="id" type="string" required>
  The device's unique identifier (e.g., `dev_abc123`).
</ParamField>

<ParamField path="commandId" type="string" required>
  The command's unique identifier (e.g., `cmd_xyz789`).
</ParamField>

## Response

Returns the command object with `status` set to `cancelled`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "cmd_xyz789",
    "device_id": "dev_abc123",
    "type": "start_recording",
    "status": "cancelled",
    "params": {
      "max_duration_sec": 3600,
      "upload_immediately": true
    },
    "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "result": null,
    "error": null,
    "expires_at": "2025-01-20T11:00:00Z",
    "delivered_at": null,
    "executed_at": null,
    "created_at": "2025-01-20T10:55:00Z"
  }
  ```

  ```json 400 (Already Executed) theme={null}
  {
    "error": {
      "code": "command_not_cancellable",
      "message": "Command has already been executed and cannot be cancelled"
    }
  }
  ```

  ```json 400 (Already Delivered) theme={null}
  {
    "error": {
      "code": "command_not_cancellable",
      "message": "Command has been delivered to device and cannot be cancelled"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Command not found"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field          | Type           | Description                           |
| -------------- | -------------- | ------------------------------------- |
| `id`           | string         | Command identifier                    |
| `device_id`    | string         | Target device (`dev_*`)               |
| `type`         | string         | `start_recording` or `stop_recording` |
| `status`       | string         | `cancelled`                           |
| `params`       | object         | Command parameters                    |
| `result`       | object \| null | Always null for cancelled commands    |
| `error`        | object \| null | Always null for cancelled commands    |
| `expires_at`   | string \| null | Original expiration timestamp         |
| `delivered_at` | string \| null | Always null for cancelled commands    |
| `executed_at`  | string \| null | Always null for cancelled commands    |
| `created_at`   | string         | Creation timestamp (ISO 8601)         |

## Notes

* Only commands in `pending` status can be cancelled
* Commands that have been `delivered`, `executed`, `failed`, or `expired` cannot be cancelled
* Cancellation is immediate and the command will not be delivered to the device