Send a command to a terminal or stream

POST

/control

const url = 'https://legion.picogrid.com/v2/control';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"namespace":"VAPIX","quality_of_service":"AT_MOST_ONCE","command":"example_command","payload":{"data":{"camera":"1","pan":"180","tilt":"0","zoom":"5000"},"method":"GET","path":"/axis-cgi/com/ptz.cgi"},"stream_id":"123e4567-e89b-12d3-a456-426614174000","terminal_id":"pg000"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://legion.picogrid.com/v2/control \
  --header 'Content-Type: application/json' \
  --data '{ "namespace": "VAPIX", "quality_of_service": "AT_MOST_ONCE", "command": "example_command", "payload": { "data": { "camera": "1", "pan": "180", "tilt": "0", "zoom": "5000" }, "method": "GET", "path": "/axis-cgi/com/ptz.cgi" }, "stream_id": "123e4567-e89b-12d3-a456-426614174000", "terminal_id": "pg000" }'

Execute a command on a specific terminal or stream. This endpoint supports various namespaces, each with its own set of commands and payload structures. Refer to the namespace-specific documentation for details on available commands and their required payloads.

Request Body^required

The command to be executed

application/json

Represents a request to execute a command on a terminal or stream. This structure allows for flexible command execution across different terminals and device types.

object

namespace

required

The namespace of the command, indicating the command set or API being used. Refer to the Command documentation for a list of supported namespaces.

string

Example

VAPIX

quality_of_service

required

Specifies the quality of service for the command execution:

AT_MOST_ONCE: The command is sent once without guarantee of execution. Suitable for non-critical operations.
GUARANTEED: The command is guaranteed to be executed at least once. This involves queuing and retry mechanisms.

string

Allowed values: AT_MOST_ONCE GUARANTEED

Example

GUARANTEED

command

The name of the command to be executed. This should be a valid command within the specified namespace. Refer to the Command documentation for available commands.

string

Example

example_command

payload

Command-specific payload containing parameters required for the command execution. The structure varies depending on the namespace and command. Refer to the namespace-specific documentation for required parameters.

object

key

additional properties

Example

{
  "data": {
    "camera": "1",
    "pan": "180",
    "tilt": "0",
    "zoom": "5000"
  },
  "method": "GET",
  "path": "/axis-cgi/com/ptz.cgi"
}

stream_id

An identifier for the target stream. This is typically used for commands that operate on specific streams for a specific terminal.

string

Example

123e4567-e89b-12d3-a456-426614174000

terminal_id

The identifier of the target terminal. This is used for commands that operate on the terminal level rather than a specific stream.

string

Example

pg000

Responses

200

Command accepted and executed successfully

application/json

Represents the response to a command execution request. The structure provides information about the command’s processing status and any relevant results.

object

command_id

A unique identifier for the command request. This can be used for tracking or referencing the command execution. This is only generated for commands with a quality of service of ‘GUARANTEED’.

string format: uuid

message

required

A human-readable message providing additional context about the command status. This can include details about success, failure reasons, or next steps.

string

status

required

The current status of the command execution. Possible values are:

ACCEPTED: The command was accepted for processing
REJECTED: The command was not accepted for processing
SUCCESS: The command was successfully executed
FAILED: The command failed during execution

string

Allowed values: ACCEPTED REJECTED SUCCESS FAILED

result

Command-specific result data. The structure varies depending on the executed command. This is typically present for SUCCESS or FAILED statuses. Refer to the specific command documentation for details on the expected result structure.

object

key

additional properties

Example

{
  "command_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Command execution was accepted.",
  "status": "ACCEPTED",
  "result": {
    "newPosition": {
      "pan": 45,
      "tilt": 30,
      "zoom": 2
    }
  }
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

400

Bad Request Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

401

Authentication Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

403

Unauthorized Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

404

Resource Not Found Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

408

Timeout Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

500

Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

502

Bad Gateway Error

application/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

Version 2 · commit 0771262

Send a command to a terminal or stream

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Responses

200

Example

Headers

Example

400

Examplegenerated

Headers

Example

401

Examplegenerated

Headers

Example

403

Examplegenerated

Headers

Example

404

Examplegenerated

Headers

Example

408

Examplegenerated

Headers

Example

500

Examplegenerated

Headers

Example

502

Examplegenerated

Headers

Example

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated