Acknowledge a relayed command for one structure

POST /api/v1/cms/commands/{id}/acks

https://app.tanba-ooh.kz/api/v1/cms/commands/{id}/acks

Scope relay:commands. Operator organisations only. Say what became of the command on one structure of the installation: ok true once it is executed, false with a short error when it could not be. The platform records the time from the signature to this call, shows it on the delivery board as relayed and not verified on the device, and, for an executed cut-off or restore, updates the state of the structure's players. An answer for a structure that was never handed this command is not found. A second answer for the same structure is ignored and returns the first. When ok is true, state must be the state the command sets: blackout after a cut-off, default after a restore, the scenario named in the command after a content switch or emergency broadcast; any other state is refused with 422.

Authentication

API key in the Authorization header.

Scope: relay:commands

Parameters

Name	In	Type	Required	Description	Example
`id`	path	string (uuid)	yes	Identifier of the command.	`01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd`
`installation`	query	string (uuid)	yes	Identifier of the registered CMS installation.	`5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50`

Request body

`application/json`

Name	Type	Required	Description	Example
`structure`	string	yes	Code of the structure.	`"ALM-0012"`
`ok`	boolean	yes	True when the command was executed on the structure's players.	`true`
`state`	string		State the players are in now, for example `blackout` or `default`.	`"blackout"`
`error`	string		Why the command could not be executed; empty on success.	`""`

Example

{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}

Responses

200 The answer was recorded, or an earlier one is returned.

`application/json`

Name	Type	Required	Description	Example
`command_id`	string (uuid)	yes	Identifier of the command.	`"01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd"`
`structure`	string	yes	Code of the structure.	`"ALM-0012"`
`ok`	boolean	yes	The recorded outcome.	`true`
`acked_at`	string (date-time)	yes	When the answer was recorded.	`"2026-10-14T09:00:07+05:00"`
`acked_in_s`	integer	yes	Seconds from the signature of the command to the answer.	`7`

Example

{
  "command_id": "01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd",
  "structure": "ALM-0012",
  "ok": true,
  "acked_at": "2026-10-14T09:00:07+05:00",
  "acked_in_s": 7
}

Errors

Errors are problem documents (application/problem+json) with a stable code.

Status	Meaning
401	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
404	Nothing there, or not visible to the caller.
409	The installation is retired (`installation_retired`).
422	Field errors (`validation_failed`).
429	Rate limit; see `Retry-After`.
default	An error as a problem document.

Code samples

curl

curl -X POST 'https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}'

Python

import requests

response = requests.post(
    "https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "structure": "ALM-0012",
        "ok": True,
        "state": "blackout",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}`)
	req, err := http.NewRequest("POST", "https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}