Skip to content
Picogrid Legion

Register MQTT topics for one command or many

Register MQTT topics for one command or many

Open in ChatGPT ↗Open in Claude ↗
POST
/v3/tasking/entity/{entityId}/mqtt-topics
curl --request POST \
  --url https://api.hopper.west.prod.govcloud.legion.picogrid.com/v3/tasking/entity/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/mqtt-topics \
  --header 'Content-Type: application/json' \
  --data '{ "command_name": "restart", "entity_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "request_mqtt_topic": "HS1040/task/request/aws/restart", "response_mqtt_topic": "HS1040/task/response/aws/restart" }'

Registers the request/response MQTT topic pair for commands on the specified entity. Accepts either the legacy single-command form or the bulk map form on one URL; the response mirrors whichever form arrived (the flat topic object for the single form, the results envelope for the bulk form). Registering N commands one at a time costs N requests; the bulk form costs one. Existing topics for a command name are updated, so the call is idempotent and safe to retry. In the bulk form, either every topic pair is written or none is.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
entityId
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
command_name
required
string
Example
restart
entity_id
required
string format: uuid
request_mqtt_topic
required
string
Example
HS1040/task/request/aws/restart
response_mqtt_topic
required
string
Example
HS1040/task/response/aws/restart

Responses

Section titled “Responses”

201

Section titled “201”

Resource created successfully

Media typeapplication/json
One of:
object
command_name
required
string
created_at
required
string
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/
entity_id
required
string format: uuid
id
required
string format: uuid
request_mqtt_topic
required
string
response_mqtt_topic
required
string
updated_at
required
string
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/
Example
{
  "command_name": "restart",
  "created_at": "2023-01-01T10:00:00Z",
  "request_mqtt_topic": "HS1040/task/request/aws/restart",
  "response_mqtt_topic": "HS1040/task/response/aws/restart",
  "updated_at": "2023-01-15T15:30:45Z"
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 400,
  "details": [
    {
      "Field": "organization_id",
      "Issue": "must be a valid UUID format"
    }
  ],
  "message": "Request cannot be processed due to invalid input",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 401,
  "details": [
    {
      "Field": "authorization_header",
      "Issue": "Bearer token is expired or malformed"
    }
  ],
  "message": "Authentication credentials are missing or invalid",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 403,
  "details": [
    {
      "Field": "required_scope",
      "Issue": "requires 'orion:settings:write' scope, but token only has 'orion:settings:read'"
    }
  ],
  "message": "Access denied: insufficient permissions for this resource",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

409

Section titled “409”

Conflict

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 409,
  "details": [
    {
      "field": "email",
      "issue": "must be a valid email address"
    }
  ],
  "message": "Request conflicts with current state of the resource",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 422,
  "details": [
    {
      "field": "email",
      "issue": "must be a valid email address"
    }
  ],
  "message": "Request data is well-formed but violates business rules",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

500

Section titled “500”

Internal Server Error

Media typeapplication/json
object
category
required

The category of the error

string
code
required

The HTTP status code

number
details

Additional details about the error

Array<object>
object
field

The field that caused the error

string
issue

The specific issue with the field

string
message
required

A human-readable error message

string
status
required

The status of the response, always ‘error’ for error responses

string
timestamp
required

The timestamp when the error occurred

string format: date-time
trace_id
required

A unique identifier for tracing the error

string format: uuid
Example
{
  "category": "server_error",
  "code": 500,
  "details": [
    {
      "field": "field_name",
      "issue": "Field validation issue"
    }
  ],
  "message": "Internal Server Error",
  "status": "error",
  "timestamp": "2024-03-15T10:30:00Z",
  "trace_id": "b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f"
}

Version 3.14.0 · commit 0771262