> ## Documentation Index
> Fetch the complete documentation index at: https://learn.servitly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get command payload
> Retrieves the payload of the command for a deferred execution on the thing.
This API will return the string-encoded payload of the command.
If the command-definition contains the USER_AUTHORIZATION_IDS parameter (used for white-listing) one string-encoded payload is generated for each authorization id.
The string-encoded payload contains the following properties:
- ts: The timestamp UTC (in seconds) referred to the payload creation time.
- sta: The timestamp UTC (in seconds) referred to the payload validity start time.
- stp: The timestamp UTC (in seconds) referred to the payload validity stop time.
- aid: The user to thing authorization identifier.
- pid: A random identifier generated on each request.
- cmd: The name of the command.
- dat: The object holding all the command parameters.
- page: The multiple payload splitting information (present in case the USER_AUTHORIZATION_IDS is used) in the format 0xXXYY, where:
- XX is the hexadecimal number identifying the total number of authorization ids.
- YY is the hexadecimal number identifying the authorization index.
In case the command-definition is secure, the payload is encrypted with the Shared Key (AES certificate) configured on the Thing, and then Base64 encoded.
Required permissions: READ_THING, EXECUTE_THING_COMMAND.
## OpenAPI
````json GET /data/commands
{
"openapi": "3.1.0",
"info": {
"title": "Servitly DPS API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.servitly-sandbox.com",
"description": "[AWS SANDBOX]"
},
{
"url": "https://api.servitly.com",
"description": "[AWS PRODUCTION Ireland]"
},
{
"url": "https://api-ap.servitly.com",
"description": "[AWS Hong Kong]"
},
{
"url": "https://azapi.servitly-dev.com",
"description": "[AZURE DEV Frankfurt]"
},
{
"url": "https://azapi.servitly-staging.com",
"description": "[AZURE STAGING Frankfurt]"
},
{
"url": "https://azapi.servitly.com",
"description": "[AZURE PRODUCTION Frankfurt]"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "ACTIONS"
},
{
"name": "ALERTS"
},
{
"name": "API GATEWAY"
},
{
"name": "AUTHENTICATION"
},
{
"name": "AUTHORIZATIONS"
},
{
"name": "CUSTOMERS"
},
{
"name": "DATA IMPORT / EXPORT"
},
{
"name": "EVENTS"
},
{
"name": "LOCATIONS"
},
{
"name": "MAINTENANCE"
},
{
"name": "MAPPING"
},
{
"name": "METRIC DATA"
},
{
"name": "MOBILE APP"
},
{
"name": "ORGANIZATION"
},
{
"name": "PARTNERS"
},
{
"name": "PRODUCT MODELS"
},
{
"name": "SPARE PARTS"
},
{
"name": "STATISTICS"
},
{
"name": "STORE ORDERS"
},
{
"name": "SUBSCRIPTIONS"
},
{
"name": "SUBSCRIPTIONS (OLD)"
},
{
"name": "THING CONTROL"
},
{
"name": "THING DEFINITIONS"
},
{
"name": "THING MANAGEMENT"
},
{
"name": "THINGS"
},
{
"name": "TICKETS"
},
{
"name": "USER TYPES"
},
{
"name": "USERS"
},
{
"name": "WORK SESSIONS"
}
],
"paths": {
"/data/commands": {
"get": {
"summary": "Get command payload",
"description": "Retrieves the payload of the command for a deferred execution on the thing.
This API will return the string-encoded payload of the command.
If the command-definition contains the USER_AUTHORIZATION_IDS parameter (used for white-listing) one string-encoded payload is generated for each authorization id.
The string-encoded payload contains the following properties:
- ts: The timestamp UTC (in seconds) referred to the payload creation time.
- sta: The timestamp UTC (in seconds) referred to the payload validity start time.
- stp: The timestamp UTC (in seconds) referred to the payload validity stop time.
- aid: The user to thing authorization identifier.
- pid: A random identifier generated on each request.
- cmd: The name of the command.
- dat: The object holding all the command parameters.
- page: The multiple payload splitting information (present in case the USER_AUTHORIZATION_IDS is used) in the format 0xXXYY, where:
- XX is the hexadecimal number identifying the total number of authorization ids.
- YY is the hexadecimal number identifying the authorization index.
In case the command-definition is secure, the payload is encrypted with the Shared Key (AES certificate) configured on the Thing, and then Base64 encoded.
Required permissions: READ_THING, EXECUTE_THING_COMMAND.",
"tags": [
"THING CONTROL"
],
"parameters": [
{
"$ref": "#/components/parameters/tenantNameHeader"
},
{
"$ref": "#/components/parameters/thingId"
},
{
"in": "query",
"name": "commandName",
"required": "true",
"schema": {
"type": "string",
"maximum": "1"
},
"description": "The command name whose payload must be retrieved."
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommandPayload"
}
}
}
},
"401": {
"$ref": "#/components/responses/NotAuthenticated"
},
"403": {
"$ref": "#/components/responses/NotAuthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/ApiLimit"
},
"500": {
"$ref": "#/components/responses/IntError"
}
}
}
}
},
"components": {
"parameters": {
"tenantNameHeader": {
"in": "header",
"name": "X-Servitly-Tenant",
"required": "true",
"schema": {
"type": "string",
"example": "{{tenantName}}"
},
"description": "The name of the tenant (e.g. acme)."
},
"thingId": {
"in": "query",
"name": "thingId",
"required": "false",
"schema": {
"type": "string",
"example": "abcd1234"
},
"description": "Condition on thing id."
}
},
"schemas": {
"CommandPayload": {
"type": "object",
"properties": {
"payloads": {
"description": "The array of string-encoded payloads.",
"type": "array",
"items": {
"type": "string",
"example": "{\"ts\":1605179226000,\"aid\":\"0x5752600086677582500510006620000000000000000000000000000000000000\",\"sta\":1579015139,\"stp\":1894634339,\"cmd\":\"Clean\",\"dat\":{\"clean\":true},\"pid\":1426857182}"
}
}
}
}
},
"responses": {
"NotAuthenticated": {
"description": "User not authenticated.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "User not authenticated"
}
}
}
}
}
},
"NotAuthorized": {
"description": "User not authorized.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "User not authorized"
}
}
}
}
}
},
"NotFound": {
"description": "Resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "Resource not found"
}
}
}
}
}
},
"ApiLimit": {
"description": "API call rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "API call rate limit exceeded"
}
}
}
}
}
},
"IntError": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
````