# Run commands

`POST /v1/outputs/{id}/commands`

Runs a batch of [commands](https://docs.airframe.tv/api/commands) on an output, in order. They all run under one revision, and all or nothing: if one can't run, nothing changes on air.

## Path parameters

- `id` (string, required): The output's id. It's the last part of the output's browser source URL.

## Body

- `commands` (Command[], required): 1 to 100 [commands](https://docs.airframe.tv/api/commands): `in`, `out`, `update`, `invoke` or `timer`.

## Response

- `revision` (integer): The output's revision after the batch. It goes up with every change, so you can tell which state came after which.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | A command isn't one of the shapes above, or the batch is empty or over 100. |
| 403 | `forbidden` | The key doesn't control this output. |
| 404 | `not_found` | No such output. |
| 422 | `command_failed` | A command couldn't run. `index` says which. Nothing changed. |
| 429 | `rate_limited` | Too many batches from this key. Retry after `Retry-After` seconds. |

## Example request

```sh
curl -X POST https://api.airframe.tv/v1/outputs/OUTPUT_ID/commands \
  -H "Authorization: Bearer $AIRFRAME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "commands": [
    {
      "command": "update",
      "component": "lower-third",
      "data": {
        "name": "Jane Doe",
        "title": "Head coach"
      }
    },
    {
      "command": "in",
      "component": "lower-third"
    },
    {
      "command": "timer",
      "timer": "match-clock",
      "action": "start"
    }
  ]
}'
```

### 200 OK

```json
{
  "revision": 42
}
```

### 422 Failed

```json
{
  "error": "No component lower-thrid",
  "code": "command_failed",
  "index": 1
}
```