Commands API

API Version: V2

Note

Base URL: https://your.iax.fqdn.com/api/obcerv-app-api-gateway/v2

To access the Commands API V1 documentation, see Commands API V1.

The ITRS Commands API provides an interface for registering commands, executing commands, monitoring command execution status and output, and managing fine-grained command permissions in ITRS Analytics.

Command Registry Copied

The Command Registry endpoints manage command definitions and registered command services.

Insert or update a single command definition Copied

Endpoint: PUT /commands
Description: Insert or update a single command definition.

Upsert a single command definition. Inserts or updates one command for its owning service. Prefer RegisterCommands when publishing a full command set from a Gateway. Commands may include optional commandGroups used with fine-grained command permissions.

Request Copied

Parameter	Type	Location	Required	Description
command	Command	Body	Yes	The command definition to insert or update.
id	CommandId	Body	Yes	Unique identifier for the command (service + name).
targets	array of CommandTargetFilter	Body	Yes	The targets the command applies to.
displayName	string	Body	No	The command’s display name.
resources	array of string	Body	No	IAM resources that restrict viewing or executing this command.
categories	array of string	Body	No	Categories used for filtering and grouping similar commands.
arguments	array of CommandArgumentTypeEntry	Body	No	The command’s arguments.
description	string	Body	No	The command’s description.
commandGroups	array of string	Body	No	Optional group names used to group related commands and scope command permissions.

Example Request Copied

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "displayName": "Manual",
    "commandGroups": [
      "snooze"
    ],
    "categories": [
      "Snooze",
      "Manual"
    ],
    "targets": [
      {
        "entity": {}
      }
    ]
  }
}

Response Copied

Success (200 OK):

{}

Delete a command from a service Copied

Endpoint: DELETE /commands
Description: Delete a command from a service.

Removes a single command definition from a service. Parameters are supplied as query string fields.

Request Copied

Parameter	Type	Location	Required	Description
serviceNamespace	string	Query	Yes	The service namespace of the command to delete.
serviceName	string	Query	Yes	The service name of the command to delete.
name	string	Query	Yes	The name of the command to delete.

Example Request Copied

DELETE /commands?serviceNamespace=serviceNamespace&serviceName=serviceName&name=name

Response Copied

Success (200 OK):

{}

Query configured commands for a target and/or service Copied

Endpoint: POST /commands/query
Description: Query configured commands for a target and/or service.

This endpoint returns registered command definitions for use in UIs such as Entity Viewer. Results can be narrowed by service (for example a Geneos Gateway), command name, command group, free-text search, or the entity/metric/log target the user selected.

When a command service has supportsPermissions enabled, results are filtered by the caller’s ITRS Analytics roles against that service’s command permissions. Services without permissions enabled are unaffected.

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	No	When set, only commands for this service are returned.
name	string	Body	No	When set, only commands with this exact name are returned.
target	CommandTarget	Body	No	When set, only commands that apply to this entity, metric, or log target are returned.
commandGroup	string	Body	No	When set, only commands in this command group are returned.
searchTerm	string	Body	No	When set, only commands whose display name or categories contain this term are returned (case-insensitive substring match).
excludeFilters	boolean	Body	No	When true, command target filters are omitted from the response to reduce payload size. Defaults to `false`.
skip	integer	Body	No	Number of matching commands to skip before returning results. Defaults to `0`.
limit	integer	Body	No	Maximum number of commands to return. Defaults to `100`.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "gateway",
          "value": "Test Gateway"
        },
        {
          "key": "probe",
          "value": "infra-probe"
        },
        {
          "key": "managedEntity",
          "value": "app-server"
        }
      ]
    }
  },
  "commandGroup": "snooze",
  "skip": 0,
  "limit": 100
}

Response Copied

Success (200 OK):

{
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/geneos",
          "name": "Test Gateway"
        },
        "name": "/SNOOZE:manual"
      },
      "displayName": "Manual",
      "commandGroups": [
        "snooze"
      ],
      "categories": [
        "Snooze",
        "Manual"
      ]
    }
  ],
  "hasMore": false
}

Register or replace all commands for a service Copied

Endpoint: POST /commands/register
Description: Register or replace all commands for a service.

This is the primary registration endpoint used by command providers such as Geneos Gateways. All commands must share the same service definition. Commands present in the request are added or updated; commands previously registered for the service but omitted from a complete (final) request are deleted. Supplying an empty commands list on a complete request deletes all commands for the service.

Requests can be batched by setting isIncomplete to true. The API then returns a registrationToken that must be supplied on subsequent batches. The final batch must include the token with isIncomplete set to false.

Set supportsPermissions to true to enable fine-grained command permissions for the service. After registration completes, publish permissions with PutCommandPermissions. When supportsPermissions is true and no permissions are published, users are denied access to the service’s commands (default-deny).

Validation mode Copied

Use validationMode to control how invalid commands are handled:

VALIDATION_MODE_STRICT (default) — if any command fails validation, the entire request is rejected. Omitting validationMode preserves this existing strict behavior.
VALIDATION_MODE_LENIENT — valid commands are registered, while invalid commands are not registered and are returned in rejected as RejectedCommand entries (index, name, reason). In lenient mode:
- If all commands are rejected, the request still succeeds with added, updated, and deleted set to 0. Existing commands for the service are preserved.
- If the request contains duplicate command names, the first occurrence is kept and subsequent duplicates are rejected.

Batched registration and validation Copied

When using isIncomplete and registrationToken with lenient validation:

Intermediate responses return the registrationToken plus rejected entries for that batch only. Previous batch rejections are not repeated on later responses.
Only valid commands are accumulated across batches.
added, updated, and deleted counts are meaningful only on the final (complete) batch.

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	Yes	The service that owns the commands being registered.
commands	array of Command	Body	Yes	The commands to register. All commands must be for the same service. An empty list on a complete request deletes all commands for the service.
filters	array of CommandTargetFilter	Body	No	Optional service-level filters that apply to all commands for this service.
isIncomplete	boolean	Body	No	When `true`, this request is a partial batch and a registrationToken is returned for subsequent batches. Defaults to `false`.
registrationToken	string	Body	No	Token returned from a previous incomplete registration batch. Required for subsequent batches of the same registration.
supportsPermissions	boolean	Body	No	When `true`, enables fine-grained command permissions for this service. Defaults to `false`.
validationMode	enum	Body	No	How invalid commands are handled. Defaults to `VALIDATION_MODE_STRICT`. Use `VALIDATION_MODE_LENIENT` to register valid commands and return rejected ones in rejected.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "filters": [
    {
      "entity": {
        "entityFilter": {
          "dimensions": {
            "dimensions": {
              "probe": "Test Probe",
              "managedEntity": "Test ME"
            }
          }
        }
      }
    }
  ],
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/geneos",
          "name": "Test Gateway"
        },
        "name": "/SNOOZE:manual"
      },
      "displayName": "Manual",
      "commandGroups": ["snooze"],
      "categories": ["Snooze", "Manual"],
      "targets": [
        {
          "entity": {
            "entityFilter": {
              "dimensions": {
                "dimensions": {
                  "probe": "Test Probe",
                  "managedEntity": "Test ME"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Response Copied

Success (200 OK):

{
  "added": 2,
  "updated": 1,
  "deleted": 1,
  "rejected": [
    {
      "index": 1,
      "name": "",
      "reason": "Command at index '1' must have a name"
    }
  ]
}

In VALIDATION_MODE_STRICT, rejected is omitted. In VALIDATION_MODE_LENIENT, rejected is present (and may be an empty list). For incomplete batches, the response also includes registrationToken.

Retrieve a registered command service Copied

Endpoint: GET /commands/service
Description: Retrieve a registered command service.

Returns metadata for a registered command service (for example, a Geneos Gateway), including its service-level filters, registered command names, and whether fine-grained command permissions are enabled with supportsPermissions.

Request Copied

Parameter	Type	Location	Required	Description
namespace	string	Query	Yes	The service namespace.
name	string	Query	Yes	The service name.

Example Request Copied

GET /commands/service?namespace=namespace&name=name

Response Copied

Success (200 OK):

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "commands": [
    "/SNOOZE:manual",
    "/SNOOZE:unsnooze"
  ],
  "supportsPermissions": true
}

Command Execution Copied

The Command Execution endpoints manage the lifecycle of command execution, from triggering commands to monitoring status, output, history, cancellation, and time-to-live updates.

Submit a command for execution Copied

Endpoint: POST /commands/execution
Description: Submit a command for execution.

Submits a command for execution. Queues a registered command for execution against the supplied entity, metric, or log target. The owning command service (for example, a Geneos Gateway) claims and runs the command, then reports status via the command execution status endpoints.

When the service has supportsPermissions enabled, the caller must be permitted by that service’s command permissions. Otherwise, the request fails with permission denied. IAM resource scopes on the command definition (if any) are also enforced.

Request Copied

Parameter	Type	Location	Required	Description
command	ExecutingCommand	Body	Yes	The command instance to execute.
command.id	CommandId	Body	Yes	Identity of the registered command to execute (service + command name).
command.target	CommandTarget	Body	Yes	Entity, metric, or log target against which the command should run.
command.arguments	array of CommandArgumentEntry	Body	No	Argument values required by the command definition. Required only when the command definition marks specific arguments as required.
command.executionGroup	string	Body	No	Optional execution group used to correlate related command executions.

Example Request Copied

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "gateway",
            "value": "Test Gateway"
          },
          {
            "key": "probe",
            "value": "infra-probe"
          },
          {
            "key": "managedEntity",
            "value": "app-server"
          }
        ]
      }
    }
  }
}

Response Copied

Success (200 OK):

{
  "execId": "2",
  "status": {
    "state": "TRIGGERED"
  }
}

Clear historical command execution entries Copied

Endpoint: DELETE /commands/execution/history
Description: Clear historical command execution entries for a user.

Request Copied

Parameter	Type	Location	Required	Description
from	string (date-time)	Query	No	Clear commands that terminated after this point in time.
to	string (date-time)	Query	No	Clear commands that terminated before this point in time. Defaults to the current time if not supplied.

Example Request Copied

DELETE /commands/execution/history?from=from&to=to

Response Copied

Success (200 OK):

{}

Returns all triggered commands for a service Copied

Endpoint: POST /commands/execution/query
Description: Returns commands that have been triggered for the supplied service. A FAILED_PRECONDITION error is returned if the supplied service is not recognized by the app.

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	No	If set, only returns the commands destined for the supplied service.
limit	integer	Body	No	The maximum number of commands to return.
skip	integer	Body	No	The number of results to skip.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "limit": 20,
  "skip": 0
}

Response Copied

Success (200 OK):

{
  "commandEntries": [
    {
      "commandExecution": {
        "execId": "1",
        "command": {
          "id": {
            "service": {
              "namespace": "itrsgroup.com/obcerv/app",
              "name": "obcerv-app-notifications"
            },
            "name": "entity:notify"
          },
          "arguments": {
            "Configuration": {
              "string": "1"
            }
          },
          "target": {
            "entity": {
              "dimensions": [
                {
                  "key": "node",
                  "value": "itrsgroup.node.101.com"
                }
              ]
            }
          }
        },
        "triggeredAt": "2024-06-15T19:32:49.552871Z"
      }
    },
    {
      "commandCancellation": {
        "execId": "2",
        "cancelledBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        },
        "cancelledAt": "2024-06-15T19:33:44.553749Z"
      }
    }
  ]
}

Update the status of a command Copied

Endpoint: PUT /commands/execution/status
Description: Update the status of a command.

Request Copied

Parameter	Type	Location	Required	Description
claim	ClaimCommand	Body	No	Claim a triggered command for execution. One of `claim`, `renewClaim`, `fail`, or `output` is required.
renewClaim	RenewClaimCommand	Body	No	Renew an existing claim on a command.
fail	FailCommand	Body	No	Mark a claimed command as failed.
output	SendCommandOutput	Body	No	Send command output and optionally complete the command.

Example Request Copied

{
  "claim": {
    "claimFor": "300s",
    "execId": "1"
  }
}

Response Copied

Success (200 OK):

{
  "execId": "20",
  "claimId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  }
}

Query the status of one or more commands Copied

Endpoint: POST /commands/execution/status/query
Description: Query the status of one or more commands.

Request Copied

Parameter	Type	Location	Required	Description
from	string (date-time)	Body	No	Only return commands triggered from this time. If omitted, all commands are returned.
skip	integer	Body	No	The number of entries to skip.
limit	integer	Body	No	The maximum number of entries to return.
stateFilter	array of enum	Body	No	Only return command status entries that match any of the supplied lifecycle states.

Example Request Copied

{
  "from": "2024-06-15T05:58:31.013397Z",
  "skip": 0,
  "limit": 100,
  "stateFilter": [
    "COMMAND_LIFECYCLE_COMPLETED"
  ]
}

Response Copied

Success (200 OK):

{
  "commandStatusEntries": [
    {
      "execId": "1",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_COMPLETED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "completedAt": "2024-07-23T09:13:34.062745Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        }
      }
    },
    {
      "execId": "2",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_FAILED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        },
        "failureInfo": {
          "failedAt": "2024-07-23T09:13:34.063762Z",
          "code": "PERMISSION_DENIED",
          "message": "Insufficient permissions"
        }
      }
    },
    {
      "execId": "3",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_CANCELLED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        },
        "cancellationInfo": {
          "cancelledAt": "2024-07-23T09:13:34.064444Z",
          "reason": "Cancelled by user 'admin'"
        }
      }
    }
  ],
  "hasMore": false,
  "numEntries": 1024
}

Endpoint: POST /commands/execution/status/subscribe
Description: Subscribe to triggered command status updates.

Request Copied

Parameter	Type	Location	Required	Description
from	string (date-time)	Body	No	Subscribe from a point in the past. Defaults to the time of the request.
limit	integer	Body	No	Limits the number of completed commands returned. In-progress commands are always returned.

Example Request Copied

{
  "from": "2024-06-15T05:58:31.013397Z",
  "limit": 100
}

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: message
data: {
  "statusEntry": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "arguments": {
        "Configuration": {
          "string": "1"
        }
      },
      "target": {
        "entity": {
          "dimensions": [
            {
              "key": "node",
              "value": "itrsgroup.node.101.com"
            }
          ]
        }
      }
    },
    "status": {
      "state": "COMMAND_LIFECYCLE_FAILED",
      "triggerInfo": {
        "triggeredAt": "2024-06-15T19:48:47.549334Z",
        "triggeredBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        }
      },
      "claimInfo": {
        "claimedAt": "2024-06-15T19:48:57.551984Z",
        "claimExpiresAt": "2024-06-15T19:54:17.551994Z"
      },
      "outputInfo": {
        "lastUpdatedAt": "2024-06-15T19:49:07.554677Z"
      },
      "failureInfo": {
        "failedAt": "2024-06-15T19:49:12.555704Z",
        "code": "PERMISSION_DENIED",
        "message": "Insufficient permissions"
      }
    }
  }
}

Endpoint: POST /commands/execution/subscribe
Description: Subscribe to triggered commands for a service. A FAILED_PRECONDITION error is returned if the supplied service is not recognized by the app.

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	Yes	Only returns the commands destined for the supplied service.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Middleware Gateway"
  }
}

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: message
data: {
  "commandExecution": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "arguments": [
        {
          "key": "Configuration",
          "argument": {
            "string": "1"
          }
        }
      ],
      "target": {
        "entity": {
          "dimensions": [
            {
              "key": "node",
              "value": "itrsgroup.node.101.com"
            }
          ]
        }
      }
    },
    "triggeredAt": "2024-07-23T09:12:39.065404Z"
  }
}

Cancel a command execution Copied

Endpoint: DELETE /commands/execution/{execId}
Description: Cancel a command execution. Only applies to commands that support cancellation.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	A unique identifier for this command instance.
reason	string	Query	No	The reason for the cancellation.

Example Request Copied

DELETE /commands/execution/123?reason=reason

Response Copied

Success (200 OK):

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  }
}

Clear a historical command execution entry Copied

Endpoint: DELETE /commands/execution/{execId}/history
Description: Clear a historical command execution entry.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution ID.

Example Request Copied

DELETE /commands/execution/123/history

Response Copied

Success (200 OK):

{}

Endpoint: POST /commands/execution/{execId}/output/subscribe
Description: Subscribe to status updates and output changes for a specific command execution ID.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution ID.

Example Request Copied

POST /commands/execution/123/output/subscribe

Response Copied

Success (200 OK):

Content-Type: text/event-stream

id: 1
event: message
data: {
  "entry": {
    "status": {
      "state": "COMMAND_LIFECYCLE_FAILED",
      "triggerInfo": {
        "triggeredAt": "2024-06-15T19:48:47.549334Z",
        "triggeredBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        }
      },
      "claimInfo": {
        "claimedAt": "2024-06-15T19:48:57.551984Z",
        "claimExpiresAt": "2024-06-15T19:54:17.551994Z"
      },
      "outputInfo": {
        "lastUpdatedAt": "2024-06-15T19:49:07.554677Z"
      },
      "failureInfo": {
        "failedAt": "2024-06-15T19:49:12.555704Z",
        "code": "PERMISSION_DENIED",
        "message": "Insufficient permissions"
      }
    }
  },
  "outputStreams": {
    "outputStream": {
      "streamOperation": "STREAM_OPERATION_APPEND",
      "contentType": "text/plain",
      "output": "INFO  - Started"
    },
    "execStream": {
      "streamOperation": "STREAM_OPERATION_REPLACE",
      "contentType": "text/plain",
      "output": "Command 'tail -f app.log' returned exit code 0"
    }
  },
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "string": "1"
        }
      }
    ],
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "node",
            "value": "itrsgroup.node.101.com"
          }
        ]
      }
    }
  }
}

Extends the time-to-live of an executing command Copied

Endpoint: POST /commands/execution/{execId}/time-to-live
Description: Extends the time-to-live of an executing command.

Only commands that have been claimed can have their time-to-live extended. Commands may still be cancelled regardless of their time to live if:

The service that claimed the command fails to renew the claim on the command.
The command is cancelled directly by the user.
The command’s retention period is breached. This is highly unlikely and suggests a configuration error.

Request Copied

Parameter	Type	Location	Required	Description
execId	string	Path	Yes	The command execution ID.
execId	string	Body	Yes	The command execution ID.
extendBy	string	Body	Yes	The amount of time to extend the command’s time to live by. Added to the command’s end-of-life time, not the current time.

Example Request Copied

{
  "execId": "1",
  "extendBy": "3600s"
}

Response Copied

Success (200 OK):

{
  "endOfLife": "2024-06-15T05:58:31.013397Z"
}

Permissions Copied

The Permissions endpoints manage fine-grained role-based command permissions for registered command services.

Replace the full set of command permissions for a service Copied

Endpoint: PUT /commands/permissions
Description: Replace the full set of command permissions for a service.

This endpoint configures which ITRS Analytics roles may view and execute commands registered by a command service (for example, a Geneos Gateway). The supplied permissions list fully replaces any previously stored permissions for that service. The service must already be registered with supportsPermissions set to true. See the Register commands endpoint for more information.

Each permission entry grants access for one or more roles to commands matching commandNamePatterns (Geneos-style wildcards such as /SNOOZE:*), optionally further restricted by commandGroupNames and targets (entity/metric scope).

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	Yes	The command service whose permissions are being replaced.
permissions	array of CommandPermission	Body	Yes	The complete permission list for the service. Replaces any existing entries.
permissions[].name	string	Body	Yes	Unique permission name within the command service.
permissions[].roles	array of string	Body	Yes	IAX realm roles this permission applies to.
permissions[].targets	array of CommandPermissionTarget	Body	Yes	Entity/metric scopes for this permission. Use `[{}]` when not restricted by target.
permissions[].commandNamePatterns	array of string	Body	Yes	Command name patterns matched against `Command.id.name` (for example `/SNOOZE:*`).
permissions[].commandGroupNames	array of string	Body	No	Optional command group names that further restrict this permission.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "permissions": [
    {
      "name": "allow-snooze",
      "roles": [
        "operator"
      ],
      "targets": [
        {}
      ],
      "commandGroupNames": [
        "snooze"
      ],
      "commandNamePatterns": [
        "/SNOOZE:*"
      ]
    }
  ]
}

Response Copied

Success (200 OK):

{}

Delete command permissions for a service Copied

Endpoint: DELETE /commands/permissions
Description: Delete command permissions for a service.

Parameters are supplied as query string fields consistent with DeleteCommand. When permissionName is omitted, all permissions for the service are deleted. When set, only the named permission is removed.

Request Copied

Parameter	Type	Location	Required	Description
serviceNamespace	string	Query	Yes	The service namespace of the command service.
serviceName	string	Query	Yes	The service name.
permissionName	string	Query	No	If omitted, all permissions for the service are deleted. If set, only the named permission is removed.

Example Request Copied

DELETE /commands/permissions?serviceNamespace=serviceNamespace&serviceName=serviceName&permissionName=permissionName

Response Copied

Success (200 OK):

{}

Query command permissions for a service Copied

Endpoint: POST /commands/permissions/query
Description: Query command permissions for a service.

This endpoint returns the fine-grained command permissions currently configured for command services. Use it to inspect permissions published by a Geneos Gateway (or other command providers) after calling PutCommandPermissions or RegisterCommands. Results can be filtered by service or permission name, and paginated with skip / limit. hasMore on the response indicates additional pages.

Request Copied

Parameter	Type	Location	Required	Description
service	Service	Body	No	When set, only permissions for this command service are returned. Omit to query across all registered services.
name	string	Body	No	When set, only the permission with this name is returned.
skip	integer	Body	No	Number of matching permissions to skip before returning results. Defaults to `0`.
limit	integer	Body	No	Maximum number of permissions to return. Defaults to `100`.

Example Request Copied

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "skip": 0,
  "limit": 100
}

Response Copied

Success (200 OK):

{
  "permissions": [
    {
      "name": "allow-snooze",
      "roles": [
        "operator"
      ],
      "targets": [
        {}
      ],
      "commandGroupNames": [
        "snooze"
      ],
      "commandNamePatterns": [
        "/SNOOZE:*"
      ]
    }
  ],
  "hasMore": false
}

Configuration Copied

The Configuration endpoints expose current application configuration settings.

Returns the supported application’s current configuration settings Copied

Endpoint: GET /config
Description: Returns the supported application’s current configuration settings.

Request Copied

No parameters required.

Example Request Copied

GET /config

Response Copied

Success (200 OK):

{
  "config": {
    "rpcTimeout": "300s",
    "serviceLivenessTimeout": "300s",
    "entityCacheTtl": "300s",
    "commandRegistration": {
      "housekeepingInterval": "300s",
      "tokenTtl": "300s"
    },
    "commandExecution": {
      "claimTimeout": "300s",
      "retentionPeriod": "300s",
      "housekeepingInterval": "300s",
      "persistenceEnabled": false,
      "persistencePath": "/data/commands/rocksdb",
      "maxEntries": 10000,
      "maxHistory": 100,
      "timeToLive": "300s",
      "statsPollInterval": "300s",
      "averageEntrySizeBytes": 16384,
      "averageHistoricalEntrySizeBytes": 65536
    }
  }
}

API Information Copied

The Info endpoints expose API metadata such as supported versions.

Returns the supported API versions Copied

Endpoint: GET /versions
Description: Returns the supported API versions.

Request Copied

No parameters required.

Example Request Copied

GET /versions

Response Copied

Success (200 OK):

{
  "versions": [
    "v1",
    "v2"
  ]
}

Schemas Copied

The following request and response models are defined by the API (listed in alphabetical order).

Any Copied

Field	Type	Required	Description
value	GoogleProtobufAny	No
yaml	string	No

{
  "value": {
    "@type": "string"
  },
  "yaml": "string"
}

ArgumentType Copied

Option	Type	Description
string	StringType	One possible shape for this schema
float	FloatType	One possible shape for this schema
integer	IntegerType	One possible shape for this schema
duration	DurationType	One possible shape for this schema
timestamp	TimestampType	One possible shape for this schema
date	DateType	One possible shape for this schema
timeOfDay	TimeOfDayType	One possible shape for this schema
options	UserInputOptions	One possible shape for this schema
boolean	BooleanType	One possible shape for this schema

{
  "string": {
    "default": "string",
    "minLength": 0,
    "maxLength": 0,
    "isPassword": false,
    "isMultiLine": false
  }
}

BooleanType Copied

Field	Type	Required	Description
default	boolean	No	The default boolean.

{
  "default": false
}

CancelCommandExecutionResponse Copied

Field	Type	Required	Description
execId	string	Yes	A unique identifier for this command instance.
status	CommandStatus	Yes	The command status.

{
  "execId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  }
}

ClaimCommand Copied

Field	Type	Required	Description
claimFor	string	Yes	The duration of the claim for this command. If the claim is not renewed and the command has not been updated within this time, the command will be considered failed due to a timeout.
comment	string	No	A human readable comment.
execId	string	Yes	The command execution ID. If the command has already been claimed the call will fail.

{
  "claimFor": "300s",
  "execId": "string",
  "comment": "string"
}

ClearCommandExecutionEntryResponse Copied

Type: object

{}

ClearCommandExecutionHistoryResponse Copied

Type: object

{}

Command Copied

Field	Type	Required	Description
arguments	array of CommandArgumentTypeEntry	No	The command’s arguments.
categories	array of string	No	The command’s categories. This is used for filtering and displaying similar commands together.
commandGroups	array of string	No	Optional group names for this command. Used to group related commands and to scope command permissions. A command may belong to more than one group.
description	string	No	The command’s description.
displayName	string	No	The command’s display name.
id	CommandId	Yes
resources	array of string	No	A list of resources that restrict users from viewing or executing this command. Each resource must map to an IAM resource with scopes ‘view’ and ’execute’. Groups of users (policies) may be assigned to a resource and its scopes. The app will only show commands to users that have access to the ‘view’ scope of at least one of the supplied resources. The app will only allow users to execute commands that have access to the ’execute’ scope of at least one of the supplied resources. The scopes are mutually exclusive. Having access to the ’execute’ scope does not imply access to the ‘view’ scope. No restrictions are applied if the resources list is empty (default)
targets	array of CommandTargetFilter	Yes	The targets the command applies to.

{
  "id": {
    "service": {
      "namespace": "itrsgroup.com/geneos",
      "name": "Middleware Gateway"
    },
    "name": "snooze:manual"
  },
  "targets": [
    {
      "entity": {
        "entityFilter": {
          "expression": {
            "set": {
              "namespace": "itrsgroup.com/system",
              "name": "severity",
              "values": [
                "critical",
                "warn"
              ]
            }
          }
        }
      }
    }
  ],
  "displayName": "string",
  "resources": [
    "string"
  ],
  "categories": [
    "string"
  ],
  "arguments": [
    {
      "key": "string",
      "argument": {
        "required": false,
        "name": "string",
        "description": "string",
        "type": {
          "string": {
            "default": "string",
            "minLength": 0,
            "maxLength": 0,
            "isPassword": false,
            "isMultiLine": false
          }
        }
      }
    }
  ],
  "description": "string",
  "commandGroups": [
    "snooze"
  ]
}

CommandArgument Copied

Option	Type	Description
string	string	One possible shape for this schema
boolean	boolean	One possible shape for this schema
float	number (float)	One possible shape for this schema
integer	integer (int32)	One possible shape for this schema
duration	string	One possible shape for this schema
timestamp	string (date-time)	One possible shape for this schema
date	ZonedDate	One possible shape for this schema
timeOfDay	ZonedTimeOfDay	One possible shape for this schema

{
  "string": "string"
}

CommandArgumentEntry Copied

Field	Type	Required	Description
argument	CommandArgument	Yes
key	string	Yes	The unique command argument key

{
  "key": "string",
  "argument": {
    "string": "string"
  }
}

CommandArgumentType Copied

Field	Type	Required	Description
description	string	No	A human readable description of the argument.
name	string	Yes	A human readable name of the argument.
required	boolean	No	Whether or not this argument must be supplied.
type	ArgumentType	Yes	The argument type.

{
  "required": false,
  "name": "string",
  "description": "string",
  "type": {
    "string": {
      "default": "string",
      "minLength": 0,
      "maxLength": 0,
      "isPassword": false,
      "isMultiLine": false
    }
  }
}

CommandArgumentTypeEntry Copied

Field	Type	Required	Description
argument	CommandArgumentType	Yes
key	string	Yes	A unique key identifying this argument.

{
  "key": "string",
  "argument": {
    "required": false,
    "name": "string",
    "description": "string",
    "type": {
      "string": {
        "default": "string",
        "minLength": 0,
        "maxLength": 0,
        "isPassword": false,
        "isMultiLine": false
      }
    }
  }
}

CommandCancellationRequest Copied

Field	Type	Required	Description
cancelledAt	string (date-time)	Yes	The cancellation timestamp.
cancelledBy	User	Yes	The user that triggered the command.
execId	string	Yes	The command execution ID.
reason	string	No	The cancellation reason.

{
  "execId": "20",
  "cancelledBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs",
    "roles": [
      "admin"
    ],
    "groups": [
      "engineering-managers"
    ],
    "permissions": {
      "obcerv-app-commands": {
        "scopes": [
          "view",
          "execute"
        ]
      }
    }
  },
  "cancelledAt": "2024-06-15T05:58:31.013397Z",
  "reason": "string"
}

CommandExecutionConfig Copied

Field	Type	Required	Description
averageEntrySizeBytes	integer (int32)	No	The estimated average command entry size in bytes. The actual value is emitted as a metric named `exec_cmd_avg_val_size`.
averageHistoricalEntrySizeBytes	integer (int32)	No	The estimated average command entry size in bytes. The actual value is emitted as a metric named `exec_cmd_history_avg_val_size`.
claimTimeout	string	No	Maximum amount of time to wait for a triggered command to be claimed.
housekeepingInterval	string	No	How often to perform housekeeping on the internal command cache. This can be a computationally expensive operation.
maxEntries	integer (int32)	No	The maximum allowable number of command execution entries. This is a soft limit and is enforced by internal housekeeping tasks.
maxHistory	integer (int32)	No	The maximum number of historical entries per command execution. This is a soft limit and is enforced by internal housekeeping tasks.
persistenceEnabled	boolean	No	Whether to persist command execution history across application restarts, re-installs and upgrades.
persistencePath	string	No	The path to store currently executing and previously executed commands and their history. Only required if persistence is enabled.
retentionPeriod	string	No	The maximum amount of time to keep executed commands and their history.
statsPollInterval	string	No	The internal cache statistics poll interval. The operations involved in calculating the cache statistics are expensive and must not be done very often.
timeToLive	string	No	The time-to-live duration of an executing command. This also defines the maximum amount a user can extend the command’s end of life timestamp by. This is a soft limit and is enforced by internal housekeeping tasks.

{
  "claimTimeout": "300s",
  "retentionPeriod": "300s",
  "housekeepingInterval": "300s",
  "persistenceEnabled": false,
  "persistencePath": "/data/commands/rocksdb",
  "maxEntries": 10000,
  "maxHistory": 100,
  "timeToLive": "300s",
  "statsPollInterval": "300s",
  "averageEntrySizeBytes": 16384,
  "averageHistoricalEntrySizeBytes": 65536
}

CommandExecutionEntry Copied

Field	Type	Required	Description
command	ExecutingCommand	Yes	The executing command.
displayName	string	No	The command’s display name.
outputStreams	CommandOutputStreams	No	The command output if the command executor supplied any.
status	CommandStatus	Yes	The executing command status.

{
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  },
  "outputStreams": {
    "outputStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    },
    "errorStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    },
    "execStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    }
  },
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "gateway",
            "value": "Test Gateway"
          },
          {
            "key": "probe",
            "value": "infra-probe"
          },
          {
            "key": "managedEntity",
            "value": "app-server"
          }
        ]
      }
    }
  },
  "displayName": "Snooze"
}

CommandExecutionRequest Copied

Field	Type	Required	Description
command	ExecutingCommand	Yes	The executing command.
execId	string	Yes	The command execution ID.
triggeredAt	string (date-time)	Yes	The point in time the command was triggered.
triggeredBy	User	Yes	The user that triggered the command.

{
  "execId": "20",
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "gateway",
            "value": "Test Gateway"
          },
          {
            "key": "probe",
            "value": "infra-probe"
          },
          {
            "key": "managedEntity",
            "value": "app-server"
          }
        ]
      }
    }
  },
  "triggeredBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs",
    "roles": [
      "admin"
    ],
    "groups": [
      "engineering-managers"
    ],
    "permissions": {
      "obcerv-app-commands": {
        "scopes": [
          "view",
          "execute"
        ]
      }
    }
  },
  "triggeredAt": "2024-06-15T05:58:31.013397Z"
}

CommandId Copied

Field	Type	Required	Description
name	string	Yes	The command name.
service	Service	Yes	The service the command belongs to. It forms part of the unique identifier of a command.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Middleware Gateway"
  },
  "name": "snooze:manual"
}

CommandOutputStreams Copied

Field	Type	Required	Description
errorStream	CommandStream	No	The command error stream (equivalent to unix stderr).
execStream	CommandStream	No	The command execution output. Usually used for a high level summary of the command execution.
outputStream	CommandStream	No	The command output stream (equivalent to unix stdout).

{
  "outputStream": {
    "streamOperation": 0,
    "contentType": "string",
    "output": "string"
  },
  "errorStream": {
    "streamOperation": 0,
    "contentType": "string",
    "output": "string"
  },
  "execStream": {
    "streamOperation": 0,
    "contentType": "string",
    "output": "string"
  }
}

CommandPermission Copied

A fine-grained permission for a command service. Grants one or more IAX roles access to commands whose names match the configured patterns, optionally restricted by command group and entity/metric targets.

Required: name, roles, targets, commandNamePatterns. Optional: commandGroupNames.

Command name patterns use Geneos-style wildcards where ‘*’ matches zero or more characters (for example /SNOOZE:* matches /SNOOZE:manual and /SNOOZE:unsnooze).

Field	Type	Required	Description
commandGroupNames	array of string	No	Optional command group names that further restrict this permission. When non-empty, only commands that belong to at least one of these groups (via commandGroups) are permitted.
commandNamePatterns	array of string	Yes	Command name patterns matched against Command.id.name. The wildcard character ‘’ matches zero or more characters (for example `/SNOOZE:`). Patterns are consistent with Geneos command permission names.
name	string	Yes	Unique permission name within the command service. Used when querying or deleting a single permission.
roles	array of string	Yes	IAX realm roles this permission applies to. A user must hold at least one of these roles for the permission to match. Users with the IAX admin role bypass permission matching entirely.
targets	array of CommandPermissionTarget	Yes	One or more entity/metric scopes for this permission. Include an empty object [{}] when the permission should apply regardless of command target.

{
  "name": "allow-snooze",
  "roles": [
    "operator"
  ],
  "targets": [
    {}
  ],
  "commandGroupNames": [
    "snooze"
  ],
  "commandNamePatterns": [
    "/SNOOZE:*"
  ]
}

CommandPermissionTarget Copied

Scopes a command permission to entities and optionally a metric. An empty target (no entityFilter and no metric) means the permission is not restricted by target.

Field	Type	Required	Description
entityFilter	EntityFilter	No
metric	NamespacedName	No	If set, the permission applies only when the command target metric matches. Unset namespace or name fields act as wildcards.

{}

CommandRegistrationConfig Copied

Field	Type	Required	Description
housekeepingInterval	string	No	How often to perform housekeeping on the internal command registration module.
tokenTtl	string	No	Sets the duration of the tokens returned by the command registration endpoint.

{
  "housekeepingInterval": "300s",
  "tokenTtl": "300s"
}

CommandRegistrationToken Copied

Field	Type	Required	Description
expiry	string (date-time)	Yes	If the client does not complete the command registration prior this timestamp then the token is invalidated. This timestamp is updated after each partial client request.
token	string	Yes	The command registration token that is unique to the registration request. It must be supplied in subsequent requests to the RegisterCommands endpoint. If a registration request without a token is received for the same service, any existing token for that service is invalidated.

{
  "token": "f47ac10b58cc4372a5670e02b2c3d479",
  "expiry": "2024-06-15T05:58:31.013397Z"
}

CommandStatus Copied

Field	Type	Required	Description
cancellationInfo	CommandStatus_CommandCancellationInfo	No	Information regards the command’s cancellation. Only present if the command was cancelled.
claimInfo	CommandStatus_CommandClaimInfo	No	Information regarding the command’s claim. Only present the command has been claimed.
endOfLife	string (date-time)	Yes	The timestamp after which the command will be cancelled. This can be extended by the user that triggered the command by sending a time-to-live extension request.
failureInfo	CommandStatus_CommandFailureInfo	No	Information regarding the command’s failure. Only present if the command has failed.
outputInfo	CommandStatus_CommandOutputInfo	No	Information regarding the command’s output. Only present if the command has output.
state	integer (enum)	Yes	The current command execution lifecycle state.
triggerInfo	CommandStatus_CommandTriggerInfo	No	Information regarding the triggering of a command.

{
  "state": "COMMAND_LIFECYCLE_CANCELLED",
  "triggerInfo": {
    "triggeredAt": "2024-06-15T19:51:17.437128Z",
    "triggeredBy": {
      "username": "jbloggs",
      "displayName": "Joe Bloggs",
      "roles": [
        "admin"
      ],
      "groups": [
        "engineering-managers"
      ]
    }
  },
  "claimInfo": {
    "claimedAt": "2024-06-15T19:51:27.439549Z",
    "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
  },
  "outputInfo": {
    "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
  },
  "cancellationInfo": {
    "cancelledAt": "2024-06-15T19:51:42.444117Z",
    "reason": "Cancelled by user 'admin'"
  }
}

CommandStatusEntry Copied

Field	Type	Required	Description
command	ExecutingCommand	Yes	The executing command.
displayName	string	No	The command’s display name.
execId	string	Yes	The command execution ID.
status	CommandStatus	Yes	The executing command status.

{
  "execId": "20",
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "gateway",
            "value": "Test Gateway"
          },
          {
            "key": "probe",
            "value": "infra-probe"
          },
          {
            "key": "managedEntity",
            "value": "app-server"
          }
        ]
      }
    }
  },
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  },
  "displayName": "Snooze"
}

CommandStatus_CommandCancellationInfo Copied

Field	Type	Required	Description
cancelledAt	string (date-time)	Yes	The timestamp at the point in time the command was cancelled.
reason	string	Yes	The command cancellation reason.

{
  "cancelledAt": "2024-06-15T05:58:31.013397Z",
  "reason": "string"
}

CommandStatus_CommandClaimInfo Copied

Field	Type	Required	Description
claimExpiresAt	string (date-time)	Yes	The point in time the claim expires.
claimedAt	string (date-time)	Yes	The timestamp at the point in time the command was claimed or had its claim renewed.
comment	string	No	A comment related to the claim.

{
  "claimedAt": "2024-06-15T05:58:31.013397Z",
  "comment": "string",
  "claimExpiresAt": "2024-06-15T05:58:31.013397Z"
}

CommandStatus_CommandFailureInfo Copied

Field	Type	Required	Description
code	integer (enum)	Yes	The failure reason and status code. e.g. PERMISSION_DENIED: User ‘chris’ does not have sufficient permissions to execute command ‘Restart Pod’.
failedAt	string (date-time)	Yes	The timestamp at the point in time the command failed to execute.
message	string	Yes	The error message.

{
  "failedAt": "2024-06-15T05:58:31.013397Z",
  "code": 0,
  "message": "string"
}

CommandStatus_CommandOutputInfo Copied

Field	Type	Required	Description
completedAt	string (date-time)	Yes	The timestamp at the point in time the command completed execution.
hasErrorStream	boolean	Yes	Whether this status update has any error output.
hasExecStream	boolean	Yes	Whether this status update has any execution output.
hasOutputStream	boolean	Yes	Whether this status update has any output.
lastUpdatedAt	string (date-time)	Yes	The timestamp at the point in time the command output was last updated.

{
  "lastUpdatedAt": "2024-06-15T05:58:31.013397Z",
  "completedAt": "2024-06-15T05:58:31.013397Z",
  "hasOutputStream": false,
  "hasExecStream": false,
  "hasErrorStream": false
}

CommandStatus_CommandTriggerInfo Copied

Field	Type	Required	Description
triggeredAt	string (date-time)	Yes	The point in time the command was triggered.
triggeredBy	User	Yes	The user that triggered the command.

{
  "triggeredAt": "2024-06-15T05:58:31.013397Z",
  "triggeredBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs",
    "roles": [
      "admin"
    ],
    "groups": [
      "engineering-managers"
    ],
    "permissions": {
      "obcerv-app-commands": {
        "scopes": [
          "view",
          "execute"
        ]
      }
    }
  }
}

CommandStream Copied

Field	Type	Required	Description
contentType	string	No	The content type. Defaults to ’text/plain’. Must be a valid MIME Type as defined by https://tools.ietf.org/html/rfc2045 and https://tools.ietf.org/html/rfc2046
output	string	No	The command output.
streamOperation	integer (enum)	No	The stream operation. Must be set if the command has output.

{
  "streamOperation": 0,
  "contentType": "string",
  "output": "string"
}

CommandTarget Copied

The target of the command.

Option	Type	Description
metric	CommandTarget_Metric	One possible shape for this schema
log	CommandTarget_Log	One possible shape for this schema
entity	CommandTarget_Entity	One possible shape for this schema

{
  "metric": {
    "dimensions": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "metric": {
      "namespace": "string",
      "name": "string"
    }
  }
}

CommandTargetFilter Copied

A filter that determines the targets the command applies to. Must be set to one of entity, metric, log, or entity group.

Option	Type	Description
entity	EntityTargetFilter	One possible shape for this schema
metric	MetricTargetFilter	One possible shape for this schema
log	LogTargetFilter	One possible shape for this schema

{
  "entity": {
    "entityFilter": {
      "expression": {
        "set": {
          "namespace": "itrsgroup.com/system",
          "name": "severity",
          "values": [
            "critical",
            "warn"
          ]
        }
      }
    }
  }
}

CommandTarget_Entity Copied

Field	Type	Required	Description
dimensions	array of Dimension	Yes	Only returns commands that apply to the entity with the supplied dimensions.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

CommandTarget_Log Copied

Field	Type	Required	Description
dimensions	array of Dimension	Yes	Only returns commands that apply to the entity with the supplied dimensions.
log	NamespacedName	Yes

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "log": {
    "namespace": "string",
    "name": "string"
  }
}

CommandTarget_Metric Copied

Field	Type	Required	Description
dimensions	array of Dimension	Yes	Only returns commands that apply to the entity with the supplied dimensions.
metric	NamespacedName	Yes

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "metric": {
    "namespace": "string",
    "name": "string"
  }
}

CommandsServiceConfig Copied

Field	Type	Required	Description
commandExecution	CommandExecutionConfig	No	Command execution settings.
commandRegistration	CommandRegistrationConfig	No	Command registration settings.
entityCacheTtl	string	No	How long to cache entities fetched from the platform to evaluate command target filters against. This should be short enough such that changes to the entities are reflected in the app within a reasonable amount of time. It should be long enough for a user to interact with the UI and discover/search commands for an entity or metric.
rpcTimeout	string	No	The maximum amount of time to wait for RPCs to platform services to complete.
serviceLivenessTimeout	string	No	Maximum amount of time to wait for a service to interact with the application before failing the liveness check and all its commands being removed.

{
  "rpcTimeout": "300s",
  "serviceLivenessTimeout": "300s",
  "entityCacheTtl": "300s",
  "commandRegistration": {
    "housekeepingInterval": "300s",
    "tokenTtl": "300s"
  },
  "commandExecution": {
    "claimTimeout": "300s",
    "retentionPeriod": "300s",
    "housekeepingInterval": "300s",
    "persistenceEnabled": false,
    "persistencePath": "/data/commands/rocksdb",
    "maxEntries": 10000,
    "maxHistory": 100,
    "timeToLive": "300s",
    "statsPollInterval": "300s",
    "averageEntrySizeBytes": 16384,
    "averageHistoricalEntrySizeBytes": 65536
  }
}

DateList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
dates	array of ZonedDate	Yes	The list of dates.
default	ZonedDate	No	The default date.

{
  "dates": [
    {
      "date": "2024-06-15",
      "timezone": "string"
    }
  ],
  "default": {
    "date": "2024-06-15",
    "timezone": "string"
  },
  "allowUserInput": false
}

DateType Copied

Field	Type	Required	Description
default	ZonedDate	No	The default date.

{
  "default": {
    "date": "2024-06-15",
    "timezone": "string"
  }
}

DeleteCommandPermissionsResponse Copied

Empty response returned when command permissions were successfully deleted.

Type: object

{}

DeleteCommandResponse Copied

Empty response returned when the command was successfully deleted.

Type: object

{}

Dimension Copied

A single Entity dimension.

Field	Type	Required	Description
key	string	No
value	string	No

{
  "key": "string",
  "value": "string"
}

DurationList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	string	No	The default duration.
durations	array of string	Yes	The list of durations.

{
  "durations": [
    "300s"
  ],
  "default": "300s",
  "allowUserInput": false
}

DurationType Copied

Field	Type	Required	Description
default	string	No	The default duration.
exclusiveMax	boolean	No	Whether the maximum value is exclusive.
exclusiveMin	boolean	No	Whether the minimum value is exclusive.
max	string	No	The maximum acceptable value.
min	string	No	The minimum acceptable value.

{
  "default": "300s",
  "min": "300s",
  "max": "300s",
  "exclusiveMin": false,
  "exclusiveMax": false
}

EntityArtifactFilter Copied

Field	Type	Required	Description
names	array of NamespacedName	No	List of artifact names to match (optional). Namespace and name are required for each entry.
namesOperator	integer (enum)	No	The operator to apply to the list of names, if supplied. AND (default): All supplied names must match. OR: At least one of the supplied names must match.
types	array of integer (enum)	No	Artifact types to match (optional).

{
  "namesOperator": 0,
  "names": [
    {
      "namespace": "string",
      "name": "string"
    }
  ],
  "types": [
    0
  ]
}

EntityFilter Copied

An entity filter expressed as either an expression or an exact dimension filter.

Field	Type	Required	Description
artifactFilter	EntityArtifactFilter	No	Optionally include only entities having specific artifact(s). This can be specified alone or in tandem with the `entity_filter`.
dimensions	UnorderedDimensionsFilter	No	Exact match on an entity’s entire set of dimensions, irrespective of the order of dimensions. This can match multiple entities, i.e. those with same dimensions but different hierarchy.
expression	Expression	No	Filter by one or more entities matching an expression.
orderedDimensions	OrderedDimensionsFilter	No	Exact match on an entity’s entire set of dimensions, taking the order of dimensions into account. This can match at most one entity.

{
  "orderedDimensions": {
    "dimensions": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  },
  "dimensions": {
    "dimensions": {
      "key": "string"
    }
  },
  "expression": {
    "additionalProperties": [
      {
        "name": "string",
        "value": {
          "value": {
            "@type": "string"
          },
          "yaml": "string"
        }
      }
    ]
  },
  "artifactFilter": {
    "namesOperator": 0,
    "names": [
      {
        "namespace": "string",
        "name": "string"
      }
    ],
    "types": [
      0
    ]
  }
}

EntityTargetFilter Copied

Field	Type	Required	Description
entityFilter	EntityFilter	No	The entity filter. If not set, the command applies to all entities.

{
  "entityFilter": {
    "orderedDimensions": {
      "dimensions": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    },
    "dimensions": {
      "dimensions": {
        "key": "string"
      }
    },
    "expression": {
      "additionalProperties": [
        {
          "name": "string",
          "value": {
            "value": {
              "@type": "string"
            },
            "yaml": "string"
          }
        }
      ]
    },
    "artifactFilter": {
      "namesOperator": 0,
      "names": [
        {
          "namespace": "string",
          "name": "string"
        }
      ],
      "types": [
        0
      ]
    }
  }
}

ExecuteCommandRequest Copied

Submits a registered command for execution against a target. When the owning service has supportsPermissions enabled, the caller must match that service’s command permissions (or hold the IAX admin role).

Field	Type	Required	Description
command	ExecutingCommand	Yes	The command instance to execute, including ID, target, and any required argument values.

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "gateway",
            "value": "Test Gateway"
          },
          {
            "key": "probe",
            "value": "infra-probe"
          },
          {
            "key": "managedEntity",
            "value": "app-server"
          }
        ]
      }
    }
  }
}

ExecuteCommandResponse Copied

Identifier and initial status for a submitted command execution.

Field	Type	Required	Description
execId	string	Yes	Unique execution ID used to track status, output, cancellation, and TTL.
status	CommandStatus	Yes	Initial status of the submitted command execution.

{
  "execId": "2",
  "status": {
    "state": "TRIGGERED"
  }
}

ExecutingCommand Copied

A command instance submitted for execution, including the command ID, target, and optional argument values.

Required: ID, target. Optional: arguments, executionGroup.

Field	Type	Required	Description
arguments	array of CommandArgumentEntry	No	Argument values required by the command definition, keyed by argument key.
executionGroup	string	No	Optional execution group used to correlate related command executions.
id	CommandId	Yes	Identity of the registered command to execute (service + command name).
target	CommandTarget	Yes	Entity, metric, or log target against which the command should run.

{
  "id": {
    "service": {
      "namespace": "itrsgroup.com/geneos",
      "name": "Test Gateway"
    },
    "name": "/SNOOZE:manual"
  },
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "gateway",
          "value": "Test Gateway"
        },
        {
          "key": "probe",
          "value": "infra-probe"
        },
        {
          "key": "managedEntity",
          "value": "app-server"
        }
      ]
    }
  }
}

Expression Copied

Field	Type	Required	Description
additionalProperties	array of NamedAny	No

{
  "additionalProperties": [
    {
      "name": "string",
      "value": {
        "value": {
          "@type": "string"
        },
        "yaml": "string"
      }
    }
  ]
}

ExtendTtlRequest Copied

Field	Type	Required	Description
execId	string	Yes	The command execution ID.
extendBy	string	Yes	The amount of time to extend the command’s time to live by. This duration is added to the executing command’s end of life time, not the current time. It cannot exceed the configured maximum time to live limit which defaults to 1 hour.

{
  "execId": "1",
  "extendBy": "3600s"
}

ExtendTtlResponse Copied

Field	Type	Required	Description
endOfLife	string (date-time)	Yes	The updated end of life of the command.

{
  "endOfLife": "2024-06-15T05:58:31.013397Z"
}

FailCommand Copied

Field	Type	Required	Description
claimId	string	Yes	The command claim ID.
code	integer (enum)	Yes	The error status code.
message	string	Yes	An error message.

{
  "claimId": "string",
  "code": 0,
  "message": "string"
}

FloatList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	number (float)	No	The default option.
floats	array of number (float)	Yes	A list of float options.

{
  "floats": [
    0.0
  ],
  "default": 0.0,
  "allowUserInput": false
}

FloatType Copied

Field	Type	Required	Description
default	number (float)	No	The default value.
exclusiveMax	boolean	No	Whether the maximum value is exclusive.
exclusiveMin	boolean	No	Whether the minimum value is exclusive.
max	number (float)	No	The maximum acceptable value.
min	number (float)	No	The minimum acceptable value.

{
  "default": 0.0,
  "min": 0.0,
  "max": 0.0,
  "exclusiveMin": false,
  "exclusiveMax": false
}

GetApiVersionsResponse Copied

Field	Type	Required	Description
versions	array of string	Yes	A list of supported API versions.

{
  "versions": [
    "v1",
    "v2"
  ]
}

GetCommandServiceResponse Copied

Metadata for a registered command service, including whether fine-grained command permissions are enabled.

Field	Type	Required	Description
commands	array of string	No	A list of command names that belong to this service
filters	array of CommandTargetFilter	No	A list of filters that applies to all commands for this service
service	Service	Yes
supportsPermissions	boolean	Yes	Whether this service uses fine-grained command permissions. When true, QueryCommands and ExecuteCommand enforce permissions published for this service.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "commands": [
    "/SNOOZE:manual",
    "/SNOOZE:unsnooze"
  ],
  "supportsPermissions": true
}

GetConfigResponse Copied

Field	Type	Required	Description
config	CommandsServiceConfig	Yes	The application’s current configuration options.

{
  "config": {
    "rpcTimeout": "300s",
    "serviceLivenessTimeout": "300s",
    "entityCacheTtl": "300s",
    "commandRegistration": {
      "housekeepingInterval": "300s",
      "tokenTtl": "300s"
    },
    "commandExecution": {
      "claimTimeout": "300s",
      "retentionPeriod": "300s",
      "housekeepingInterval": "300s",
      "persistenceEnabled": false,
      "persistencePath": "/data/commands/rocksdb",
      "maxEntries": 10000,
      "maxHistory": 100,
      "timeToLive": "300s",
      "statsPollInterval": "300s",
      "averageEntrySizeBytes": 16384,
      "averageHistoricalEntrySizeBytes": 65536
    }
  }
}

GoogleProtobufAny Copied

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Field	Type	Required	Description
@type	string	No	The type of the serialized message.

{
  "@type": "string"
}

IntegerList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	integer (int32)	No	The default integer value.
integers	array of integer (int32)	Yes	A list of integer options.

{
  "integers": [
    0
  ],
  "default": 0,
  "allowUserInput": false
}

IntegerType Copied

Field	Type	Required	Description
default	integer (int32)	No	The default value.
max	integer (int32)	No	The maximum acceptable value.
min	integer (int32)	No	The minimum acceptable value.

{
  "default": 0,
  "min": 0,
  "max": 0
}

LogTargetFilter Copied

Field	Type	Required	Description
entityFilter	EntityFilter	No	The entity filter. If not set, the command applies to all entities.
log	NamespacedName	No	The log filter. If set, the command only applies to logs with the supplied namespace and/or name. Both fields are optional. Fields that are not set are treated as wildcards.

{
  "entityFilter": {
    "orderedDimensions": {
      "dimensions": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    },
    "dimensions": {
      "dimensions": {
        "key": "string"
      }
    },
    "expression": {
      "additionalProperties": [
        {
          "name": "string",
          "value": {
            "value": {
              "@type": "string"
            },
            "yaml": "string"
          }
        }
      ]
    },
    "artifactFilter": {
      "namesOperator": 0,
      "names": [
        {
          "namespace": "string",
          "name": "string"
        }
      ],
      "types": [
        0
      ]
    }
  },
  "log": {
    "namespace": "string",
    "name": "string"
  }
}

MetricTargetFilter Copied

Field	Type	Required	Description
entityFilter	EntityFilter	No	The entity filter. If not set, the command applies to all entities.
metric	NamespacedName	No	The metric filter. If set, the command only applies to logs with the supplied namespace and/or name. Both fields are optional. Fields that are not set are treated as wildcards.

{
  "entityFilter": {
    "orderedDimensions": {
      "dimensions": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    },
    "dimensions": {
      "dimensions": {
        "key": "string"
      }
    },
    "expression": {
      "additionalProperties": [
        {
          "name": "string",
          "value": {
            "value": {
              "@type": "string"
            },
            "yaml": "string"
          }
        }
      ]
    },
    "artifactFilter": {
      "namesOperator": 0,
      "names": [
        {
          "namespace": "string",
          "name": "string"
        }
      ],
      "types": [
        0
      ]
    }
  },
  "metric": {
    "namespace": "string",
    "name": "string"
  }
}

NamedAny Copied

Automatically-generated message used to represent maps of Any as ordered (name,value) pairs.

Field	Type	Required	Description
name	string	No	Map key
value	Any	No	Mapped value

{
  "name": "string",
  "value": {
    "value": {
      "@type": "string"
    },
    "yaml": "string"
  }
}

NamespacedName Copied

A namespaced name.

Field	Type	Required	Description
name	string	No	Name.
namespace	string	No	Namespace.

{
  "namespace": "string",
  "name": "string"
}

OrderedDimensionsFilter Copied

A filter that exactly matches entity dimension keys and values, taking the order of dimensions into account.

Field	Type	Required	Description
dimensions	array of Dimension	No	Dimensions (required). Cannot be empty.

{
  "dimensions": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

PutCommandExecutionStatusRequest Copied

Option	Type	Description
claim	ClaimCommand	One possible shape for this schema
renewClaim	RenewClaimCommand	One possible shape for this schema
fail	FailCommand	One possible shape for this schema
output	SendCommandOutput	One possible shape for this schema

{
  "claim": {
    "claimFor": "300s",
    "execId": "1"
  }
}

PutCommandExecutionStatusResponse Copied

Field	Type	Required	Description
claimId	string	Yes	The command claim ID.
execId	string	Yes	The command execution ID.
status	CommandStatus	Yes	The updated command status.

{
  "execId": "20",
  "claimId": "2",
  "status": {
    "state": "COMMAND_LIFECYCLE_CANCELLED",
    "triggerInfo": {
      "triggeredAt": "2024-06-15T19:51:17.437128Z",
      "triggeredBy": {
        "username": "jbloggs",
        "displayName": "Joe Bloggs",
        "roles": [
          "admin"
        ],
        "groups": [
          "engineering-managers"
        ]
      }
    },
    "claimInfo": {
      "claimedAt": "2024-06-15T19:51:27.439549Z",
      "claimExpiresAt": "2024-06-15T19:56:47.439558Z"
    },
    "outputInfo": {
      "lastUpdatedAt": "2024-06-15T19:51:37.442321Z"
    },
    "cancellationInfo": {
      "cancelledAt": "2024-06-15T19:51:42.444117Z",
      "reason": "Cancelled by user 'admin'"
    }
  }
}

PutCommandPermissionsRequest Copied

Replaces the complete set of fine-grained command permissions for a registered command service. The service must already exist and have supportsPermissions enabled.

Required: service, permissions. Each permission requires name, roles, targets, and commandNamePatterns; commandGroupNames is optional.

Each permission grants one or more IAX roles access to commands matching name patterns (and optionally command groups and entity/metric targets). The supplied list fully replaces any previously stored permissions for the service.

Field	Type	Required	Description
permissions	array of CommandPermission	Yes	The complete permission list for the service. Replaces any existing entries. An empty list clears all permissions for the service (default-deny for non-admin users when supportsPermissions is true).
service	Service	Yes

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "permissions": [
    {
      "name": "allow-snooze",
      "roles": [
        "operator"
      ],
      "targets": [
        {}
      ],
      "commandGroupNames": [
        "snooze"
      ],
      "commandNamePatterns": [
        "/SNOOZE:*"
      ]
    }
  ]
}

PutCommandPermissionsResponse Copied

Empty response returned when command permissions were successfully replaced.

Type: object

{}

PutCommandRequest Copied

Inserts or updates a single command definition for its owning service.

Field	Type	Required	Description
command	Command	Yes

{
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/geneos",
        "name": "Test Gateway"
      },
      "name": "/SNOOZE:manual"
    },
    "displayName": "Manual",
    "commandGroups": [
      "snooze"
    ],
    "categories": [
      "Snooze",
      "Manual"
    ],
    "targets": [
      {
        "entity": {}
      }
    ]
  }
}

PutCommandResponse Copied

Empty response returned when the command was successfully inserted or updated.

Type: object

{}

QueryCommandPermissionsRequest Copied

Query fine-grained command permissions configured for command services.

Filtering can be done using:

service: Restrict results to a single command service
name: Return only the permission with this exact name
skip / limit: Paginate results; check hasMore on the response for additional pages

If neither service nor name is set, permissions across all registered services are returned (subject to pagination).

Field	Type	Required	Description
limit	integer (int32)	No	Maximum number of permissions to return. Defaults to 100.
name	string	No	When set, only the permission with this name is returned (if it exists for the selected service scope).
service	Service	No	When set, only permissions for this command service are returned. Omit to query across all registered services.
skip	integer (int32)	No	Number of matching permissions to skip before returning results. Defaults to 0.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "skip": 0,
  "limit": 100
}

QueryCommandPermissionsResponse Copied

List of command permissions matching the query, plus a pagination flag.

Field	Type	Required	Description
hasMore	boolean	Yes	True when additional matching permissions exist beyond the requested page.
permissions	array of CommandPermission	No	The command permissions matching the query.

{
  "permissions": [
    {
      "name": "allow-snooze",
      "roles": [
        "operator"
      ],
      "targets": [
        {}
      ],
      "commandGroupNames": [
        "snooze"
      ],
      "commandNamePatterns": [
        "/SNOOZE:*"
      ]
    }
  ],
  "hasMore": false
}

QueryCommandsRequest Copied

Query registered command definitions.

Filtering can be done using:

service: Restrict to one command service (for example a Geneos Gateway)
name: Exact command name match
target: Only commands that apply to the selected entity, metric, or log
commandGroup: Only commands in a named group (for example snooze)
searchTerm: Match display name or categories

When a matching service has supportsPermissions enabled, results are filtered by the caller’s IAX roles (admin users bypass permission filtering).

Field	Type	Required	Description
commandGroup	string	No	When set, only commands in this command group are returned.
excludeFilters	boolean	No	When true, command target filters are omitted from the response to reduce payload size. Defaults to false.
limit	integer (int32)	No	Maximum number of commands to return. Defaults to 100.
name	string	No	When set, only commands with this exact name are returned.
searchTerm	string	No	When set, only commands whose display name or categories contain this term are returned (case-insensitive substring match).
service	Service	No	When set, only commands for this service are returned. Permissions for other services are not applied.
skip	integer (int32)	No	Number of matching commands to skip before returning results. Defaults to 0.
target	CommandTarget	No	When set, only commands that apply to this entity, metric, or log target are returned. Also used when evaluating target-scoped command permissions.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "target": {
    "entity": {
      "dimensions": [
        {
          "key": "gateway",
          "value": "Test Gateway"
        },
        {
          "key": "probe",
          "value": "infra-probe"
        },
        {
          "key": "managedEntity",
          "value": "app-server"
        }
      ]
    }
  },
  "commandGroup": "snooze",
  "skip": 0,
  "limit": 100
}

QueryCommandsResponse Copied

Commands matching the query after service, target, and permission filtering.

Field	Type	Required	Description
commands	array of Command	No	Command definitions matching the query.
hasMore	boolean	Yes	True when additional matching commands exist beyond the requested page.

{
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/geneos",
          "name": "Test Gateway"
        },
        "name": "/SNOOZE:manual"
      },
      "displayName": "Manual",
      "commandGroups": [
        "snooze"
      ],
      "categories": [
        "Snooze",
        "Manual"
      ]
    }
  ],
  "hasMore": false
}

QueryTriggeredCommandsRequest Copied

Field	Type	Required	Description
limit	integer (uint32)	No	The maximum number of commands to return.
service	Service	No	If set, only returns the commands destined for the supplied service.
skip	integer (uint32)	No	The number of results to skip.

{
  "service": {
    "namespace": "itrsgroup.com/obcerv/app",
    "name": "obcerv-app-notifications"
  },
  "limit": 20,
  "skip": 0
}

QueryTriggeredCommandsResponse Copied

Field	Type	Required	Description
commandEntries	array of TriggeredCommandEntry	No	The commands that have been triggered for the supplied service. May be empty.
hasMore	boolean	Yes	Whether there are more commands to return.

{
  "commandEntries": [
    {
      "commandExecution": {
        "execId": "1",
        "command": {
          "id": {
            "service": {
              "namespace": "itrsgroup.com/obcerv/app",
              "name": "obcerv-app-notifications"
            },
            "name": "entity:notify"
          },
          "arguments": {
            "Configuration": {
              "string": "1"
            }
          },
          "target": {
            "entity": {
              "dimensions": [
                {
                  "key": "node",
                  "value": "itrsgroup.node.101.com"
                }
              ]
            }
          }
        },
        "triggeredAt": "2024-06-15T19:32:49.552871Z"
      }
    },
    {
      "commandCancellation": {
        "execId": "2",
        "cancelledBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        },
        "cancelledAt": "2024-06-15T19:33:44.553749Z"
      }
    }
  ]
}

QueryTriggeredCommandsStatusRequest Copied

Field	Type	Required	Description
from	string (date-time)	No	Only return command that have been triggered from the supplied time. If not supplied then all commands are returned.
limit	integer (uint32)	No	The maximum number of entries to return.
skip	integer (uint32)	No	The number of entries to skip.
stateFilter	array of integer (enum)	No	Only returns command status entries that match any of the supplied lifecycle states.

{
  "from": "2024-06-15T05:58:31.013397Z",
  "skip": 0,
  "limit": 100,
  "stateFilter": [
    "COMMAND_LIFECYCLE_COMPLETED"
  ]
}

QueryTriggeredCommandsStatusResponse Copied

Field	Type	Required	Description
commandStatusEntries	array of CommandStatusEntry	No	A list of command status entries.
hasMore	boolean	No	Whether there are more status entries to return.
numEntries	integer (int32)	No	The total number of entries.

{
  "commandStatusEntries": [
    {
      "execId": "1",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_COMPLETED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "completedAt": "2024-07-23T09:13:34.062745Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        }
      }
    },
    {
      "execId": "2",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_FAILED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        },
        "failureInfo": {
          "failedAt": "2024-07-23T09:13:34.063762Z",
          "code": "PERMISSION_DENIED",
          "message": "Insufficient permissions"
        }
      }
    },
    {
      "execId": "3",
      "command": {
        "id": {
          "service": {
            "namespace": "itrsgroup.com/obcerv/app",
            "name": "obcerv-app-notifications"
          },
          "name": "entity:notify"
        },
        "arguments": [
          {
            "key": "Configuration",
            "argument": {
              "string": "1"
            }
          }
        ],
        "target": {
          "entity": {
            "dimensions": [
              {
                "key": "node",
                "value": "itrsgroup.node.101.com"
              }
            ]
          }
        }
      },
      "status": {
        "state": "COMMAND_LIFECYCLE_CANCELLED",
        "triggerInfo": {
          "triggeredAt": "2024-07-23T09:13:09.059154Z",
          "triggeredBy": {
            "username": "jbloggs",
            "displayName": "Joe Bloggs",
            "roles": [
              "admin"
            ],
            "groups": [
              "engineering-managers"
            ]
          }
        },
        "claimInfo": {
          "claimedAt": "2024-07-23T09:13:19.061917Z",
          "claimExpiresAt": "2024-07-23T09:18:39.061926Z"
        },
        "outputInfo": {
          "lastUpdatedAt": "2024-07-23T09:13:29.062715Z",
          "hasOutputStream": true,
          "hasErrorStream": true
        },
        "cancellationInfo": {
          "cancelledAt": "2024-07-23T09:13:34.064444Z",
          "reason": "Cancelled by user 'admin'"
        }
      }
    }
  ],
  "hasMore": false,
  "numEntries": 1024
}

RegisterCommandsRequest Copied

Registers or replaces the full command set for a command service (for example a Geneos Gateway).

All commands must belong to the same service. On a complete request, commands omitted from the list are deleted. Set supportsPermissions to true to enable fine-grained role-based command permissions for the service, then publish permissions with PutCommandPermissions.

Large command sets may be sent in batches using isIncomplete and registrationToken.

Set validationMode to VALIDATION_MODE_LENIENT to register valid commands while rejecting invalid ones; defaults to VALIDATION_MODE_STRICT.

Field	Type	Required	Description
service	Service	Yes	The service that owns the commands being registered
commands	array of Command	Yes	The commands to register. All commands must be for the same service. If a command omits its service, the request service is used. If any command references a different service, the request fails. An empty list on a complete request deletes all commands for the service
filters	array of CommandTargetFilter	No	Optional service-level filters that apply to all commands for this service
isIncomplete	boolean	No	When `true`, this request is a partial batch and a registrationToken is returned for subsequent batches. Defaults to `false` (complete request)
registrationToken	string	No	Token returned from a previous incomplete registration batch. Required for subsequent batches of the same registration
supportsPermissions	boolean	No	When `true`, enables fine-grained command permissions for this service. After registration, publish permissions with `PutCommandPermissions`. When `true` and no permissions are configured, users are denied access (default-deny). Defaults to `false`
validationMode	enum	No	How invalid commands are handled. `VALIDATION_MODE_STRICT` (default; also applied when omitted) rejects the entire request if any command fails validation. `VALIDATION_MODE_LENIENT` registers valid commands and returns rejected commands in the response

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Test Gateway"
  },
  "supportsPermissions": true,
  "validationMode": "VALIDATION_MODE_LENIENT",
  "filters": [
    {
      "entity": {}
    }
  ],
  "commands": [
    {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/geneos",
          "name": "Test Gateway"
        },
        "name": "/SNOOZE:manual"
      },
      "displayName": "Manual",
      "commandGroups": [
        "snooze"
      ],
      "categories": [
        "Snooze",
        "Manual"
      ],
      "targets": [
        {
          "entity": {}
        }
      ]
    }
  ]
}

RegisterCommandsResponse Copied

Counts of commands added, updated, and deleted by the registration request. A registrationToken is included only for incomplete batched registrations. rejected is included when validationMode is VALIDATION_MODE_LENIENT.

Field	Type	Required	Description
added	integer (uint32)	Yes	The number of commands that were added. Meaningful on the final (complete) batch
updated	integer (uint32)	Yes	The number of commands that were updated. Meaningful on the final (complete) batch
deleted	integer (uint32)	Yes	The number of commands that were deleted. Meaningful on the final (complete) batch
registrationToken	CommandRegistrationToken	No	Returned only when isIncomplete is `true`. Must be supplied on subsequent batches. Invalidated on expiry or when a complete request is sent
rejected	array of RejectedCommand	No	Commands rejected during validation. Present when validationMode is `VALIDATION_MODE_LENIENT` (may be empty). Omitted for `VALIDATION_MODE_STRICT`. For batched registration, contains rejections for the current batch only

{
  "added": 2,
  "updated": 1,
  "deleted": 1,
  "rejected": [
    {
      "index": 1,
      "name": "",
      "reason": "Command at index '1' must have a name"
    }
  ]
}

RejectedCommand Copied

A command that was rejected during RegisterCommands validation. Returned in rejected when validationMode is VALIDATION_MODE_LENIENT.

Field	Type	Required	Description
index	integer (uint32)	Yes	Zero-based index of the rejected command in the request commands list
name	string	No	Command name if available; empty when the command had no name
reason	string	Yes	Why the command was rejected

{
  "index": 1,
  "name": "",
  "reason": "Command at index '1' must have a name"
}

RenewClaimCommand Copied

Field	Type	Required	Description
claimFor	string	Yes	The duration of the claim for this command. If the claim is not renewed and the command has not been updated within this time, the command will be considered failed due to a timeout.
claimId	string	Yes	If a command hasn’t been claimed and a claim ID is supplied then the claim will fail.
comment	string	No	A human readable comment.

{
  "claimFor": "300s",
  "claimId": "string",
  "comment": "string"
}

Scopes Copied

Field	Type	Required	Description
scopes	array of string	No

{
  "scopes": [
    "string"
  ]
}

SendCommandOutput Copied

Field	Type	Required	Description
claimId	string	Yes	The claim ID for this command.
outputStreams	CommandOutputStreams	No	The command output.
stateOperation	integer (enum)	Yes	The command state transition operation.

{
  "claimId": "string",
  "stateOperation": 0,
  "outputStreams": {
    "outputStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    },
    "errorStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    },
    "execStream": {
      "streamOperation": 0,
      "contentType": "string",
      "output": "string"
    }
  }
}

Service Copied

Field	Type	Required	Description
name	string	Yes	The service name. Identifies the source of the command and forms part of the unique identifier of a command in order to resolve name conflicts. (e.g. myGateway).
namespace	string	Yes	The service namespace. Identifies the source of the command and forms part of the unique identifier of a command in order to resolve name conflicts. (e.g. itrsgroup.com/geneos).

{
  "namespace": "itrsgroup.com/geneos",
  "name": "Middleware Gateway"
}

Status Copied

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

Field	Type	Required	Description
code	integer (int32)	No	The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
details	array of GoogleProtobufAny	No	A list of messages that carry the error details. There is a common set of message types for APIs to use.
message	string	No	A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

StringList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	StringList_StringEntry	No	The default string entry.
entries	array of StringList_StringEntry	Yes	A list of string entries.

{
  "entries": [
    {
      "value": "string",
      "displayValue": "string"
    }
  ],
  "default": {
    "value": "string",
    "displayValue": "string"
  },
  "allowUserInput": false
}

StringList_StringEntry Copied

Field	Type	Required	Description
displayValue	string	No	The string option’s display value. If not set, the value is used as the display value.
value	string	Yes	The string argument value.

{
  "value": "string",
  "displayValue": "string"
}

StringType Copied

Field	Type	Required	Description
default	string	No	The default string value.
isMultiLine	boolean	No	Set if the input is a multi line string.
isPassword	boolean	No	Set if the input is a password.
maxLength	integer (int32)	No	The maximum string length.
minLength	integer (int32)	No	The minimum string length.

{
  "default": "string",
  "minLength": 0,
  "maxLength": 0,
  "isPassword": false,
  "isMultiLine": false
}

SubscribeTriggeredCommandOutputResponse Copied

Field	Type	Required	Description
entry	CommandExecutionEntry	No	The command status and output.

{
  "entry": {
    "status": {
      "state": "COMMAND_LIFECYCLE_FAILED",
      "triggerInfo": {
        "triggeredAt": "2024-06-15T19:48:47.549334Z",
        "triggeredBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        }
      },
      "claimInfo": {
        "claimedAt": "2024-06-15T19:48:57.551984Z",
        "claimExpiresAt": "2024-06-15T19:54:17.551994Z"
      },
      "outputInfo": {
        "lastUpdatedAt": "2024-06-15T19:49:07.554677Z"
      },
      "failureInfo": {
        "failedAt": "2024-06-15T19:49:12.555704Z",
        "code": "PERMISSION_DENIED",
        "message": "Insufficient permissions"
      }
    }
  },
  "outputStreams": {
    "outputStream": {
      "streamOperation": "STREAM_OPERATION_APPEND",
      "contentType": "text/plain",
      "output": "INFO  - Started"
    },
    "execStream": {
      "streamOperation": "STREAM_OPERATION_REPLACE",
      "contentType": "text/plain",
      "output": "Command 'tail -f app.log' returned exit code 0"
    }
  },
  "command": {
    "id": {
      "service": {
        "namespace": "itrsgroup.com/obcerv/app",
        "name": "obcerv-app-notifications"
      },
      "name": "entity:notify"
    },
    "arguments": [
      {
        "key": "Configuration",
        "argument": {
          "string": "1"
        }
      }
    ],
    "target": {
      "entity": {
        "dimensions": [
          {
            "key": "node",
            "value": "itrsgroup.node.101.com"
          }
        ]
      }
    }
  }
}

SubscribeTriggeredCommandsRequest Copied

Field	Type	Required	Description
service	Service	Yes	Only returns the commands destined for the supplied service.

{
  "service": {
    "namespace": "itrsgroup.com/geneos",
    "name": "Middleware Gateway"
  }
}

SubscribeTriggeredCommandsResponse Copied

Option	Type	Description
commandExecution	CommandExecutionRequest	One possible shape for this schema
commandCancellation	CommandCancellationRequest	One possible shape for this schema

{
  "commandExecution": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "arguments": [
        {
          "key": "Configuration",
          "argument": {
            "string": "1"
          }
        }
      ],
      "target": {
        "entity": {
          "dimensions": [
            {
              "key": "node",
              "value": "itrsgroup.node.101.com"
            }
          ]
        }
      }
    },
    "triggeredAt": "2024-07-23T09:12:39.065404Z"
  }
}

SubscribeTriggeredCommandsStatusRequest Copied

Field	Type	Required	Description
from	string (date-time)	No	Subscribe from a point in the past. Defaults to the time of request.
limit	integer (int32)	No	Limits the amount of completed commands that are returned. All commands that are in progress are returned regardless of the value of this setting.

{
  "from": "2024-06-15T05:58:31.013397Z",
  "limit": 100
}

SubscribeTriggeredCommandsStatusResponse Copied

Field	Type	Required	Description
statusEntry	CommandStatusEntry	No	The command status payload.

{
  "statusEntry": {
    "execId": "1",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/obcerv/app",
          "name": "obcerv-app-notifications"
        },
        "name": "entity:notify"
      },
      "arguments": {
        "Configuration": {
          "string": "1"
        }
      },
      "target": {
        "entity": {
          "dimensions": [
            {
              "key": "node",
              "value": "itrsgroup.node.101.com"
            }
          ]
        }
      }
    },
    "status": {
      "state": "COMMAND_LIFECYCLE_FAILED",
      "triggerInfo": {
        "triggeredAt": "2024-06-15T19:48:47.549334Z",
        "triggeredBy": {
          "username": "jbloggs",
          "displayName": "Joe Bloggs",
          "roles": [
            "admin"
          ],
          "groups": [
            "engineering-managers"
          ]
        }
      },
      "claimInfo": {
        "claimedAt": "2024-06-15T19:48:57.551984Z",
        "claimExpiresAt": "2024-06-15T19:54:17.551994Z"
      },
      "outputInfo": {
        "lastUpdatedAt": "2024-06-15T19:49:07.554677Z"
      },
      "failureInfo": {
        "failedAt": "2024-06-15T19:49:12.555704Z",
        "code": "PERMISSION_DENIED",
        "message": "Insufficient permissions"
      }
    }
  }
}

TimeOfDay Copied

Represents a time of day. The date and time zone are either not significant or are specified elsewhere. An API may choose to allow leap seconds. Related types are [google.type.Date][google.type.Date] and google.protobuf.Timestamp.

Field	Type	Required	Description
hours	integer (int32)	No	Hours of a day in 24 hour format. Must be greater than or equal to 0 and typically must be less than or equal to 23. An API may choose to allow the value “24:00:00” for scenarios like business closing time.
minutes	integer (int32)	No	Minutes of an hour. Must be greater than or equal to 0 and less than or equal to 59.
nanos	integer (int32)	No	Fractions of seconds, in nanoseconds. Must be greater than or equal to 0 and less than or equal to 999,999,999.
seconds	integer (int32)	No	Seconds of a minute. Must be greater than or equal to 0 and typically must be less than or equal to 59. An API may allow the value 60 if it allows leap-seconds.

{
  "hours": 0,
  "minutes": 0,
  "seconds": 0,
  "nanos": 0
}

TimeOfDayList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	ZonedTimeOfDay	No	The default time of day.
timesOfDay	array of ZonedTimeOfDay	Yes	The list of times of day.

{
  "timesOfDay": [
    {
      "timeOfDay": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      },
      "timezone": "string"
    }
  ],
  "default": {
    "timeOfDay": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "nanos": 0
    },
    "timezone": "string"
  },
  "allowUserInput": false
}

TimeOfDayType Copied

Field	Type	Required	Description
default	ZonedTimeOfDay	No	The default time of day.

{
  "default": {
    "timeOfDay": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "nanos": 0
    },
    "timezone": "string"
  }
}

TimestampList Copied

Field	Type	Required	Description
allowUserInput	boolean	No	Whether to allow a user-supplied option that is not part of the pre-defined list of entries.
default	string (date-time)	No	The default timestamp.
timestamps	array of string (date-time)	Yes	The list of timestamps.

{
  "timestamps": [
    "2024-06-15T05:58:31.013397Z"
  ],
  "default": "2024-06-15T05:58:31.013397Z",
  "allowUserInput": false
}

TimestampType Copied

Field	Type	Required	Description
default	string (date-time)	No	The default value value.
exclusiveMax	boolean	No	Whether the maximum value is exclusive.
exclusiveMin	boolean	No	Whether the minimum value is exclusive.
max	string (date-time)	No	The maximum acceptable value.
min	string (date-time)	No	The minimum acceptable value.

{
  "default": "2024-06-15T05:58:31.013397Z",
  "min": "2024-06-15T05:58:31.013397Z",
  "max": "2024-06-15T05:58:31.013397Z",
  "exclusiveMin": false,
  "exclusiveMax": false
}

TriggeredCommandEntry Copied

Option	Type	Description
commandExecution	CommandExecutionRequest	One possible shape for this schema
commandCancellation	CommandCancellationRequest	One possible shape for this schema

{
  "commandExecution": {
    "execId": "20",
    "command": {
      "id": {
        "service": {
          "namespace": "itrsgroup.com/geneos",
          "name": "Test Gateway"
        },
        "name": "/SNOOZE:manual"
      },
      "target": {
        "entity": {
          "dimensions": [
            {
              "key": "gateway",
              "value": "Test Gateway"
            },
            {
              "key": "probe",
              "value": "infra-probe"
            },
            {
              "key": "managedEntity",
              "value": "app-server"
            }
          ]
        }
      }
    },
    "triggeredBy": {
      "username": "jbloggs",
      "displayName": "Joe Bloggs",
      "roles": [
        "admin"
      ],
      "groups": [
        "engineering-managers"
      ],
      "permissions": {
        "obcerv-app-commands": {
          "scopes": [
            "view",
            "execute"
          ]
        }
      }
    },
    "triggeredAt": "2024-06-15T05:58:31.013397Z"
  }
}

UnorderedDimensionsFilter Copied

A filter that exactly matches entity dimension keys and values, irrespective of the order of dimensions.

Field	Type	Required	Description
dimensions	object map of string	No	Dimensions (required). Cannot be empty.

{
  "dimensions": {
    "key": "string"
  }
}

User Copied

Field	Type	Required	Description
displayName	string	No	The user’s display name (e.g. Chris Davies).
groups	array of string	No	A list of the user’s groups.
permissions	object map of Scopes	No	A map of the user’s resources to a list of scopes.
roles	array of string	No	A list of the user’s roles.
username	string	Yes	The user’s unique identifier.

{
  "username": "jbloggs",
  "displayName": "Joe Bloggs",
  "roles": [
    "admin"
  ],
  "groups": [
    "engineering-managers"
  ],
  "permissions": {
    "obcerv-app-commands": {
      "scopes": [
        "view",
        "execute"
      ]
    }
  }
}

UserInputOptions Copied

Option	Type	Description
strings	StringList	One possible shape for this schema
floats	FloatList	One possible shape for this schema
integers	IntegerList	One possible shape for this schema
durations	DurationList	One possible shape for this schema
timestamps	TimestampList	One possible shape for this schema
dates	DateList	One possible shape for this schema
timesOfDay	TimeOfDayList	One possible shape for this schema

{
  "strings": {
    "entries": [
      {
        "value": "string",
        "displayValue": "string"
      }
    ],
    "default": {
      "value": "string",
      "displayValue": "string"
    },
    "allowUserInput": false
  }
}

ZonedDate Copied

Field	Type	Required	Description
date	string (date)	Yes	The date.
timezone	string	No	The timezone.

{
  "date": "2024-06-15",
  "timezone": "string"
}

ZonedTimeOfDay Copied

Field	Type	Required	Description
timeOfDay	TimeOfDay	Yes	The time of day.
timezone	string	No	The timezone.

{
  "timeOfDay": {
    "hours": 0,
    "minutes": 0,
    "seconds": 0,
    "nanos": 0
  },
  "timezone": "string"
}

Command Lifecycle States Copied

COMMAND_LIFECYCLE_UNSPECIFIED - Default/unspecified state
COMMAND_LIFECYCLE_TRIGGERED - Command has been triggered but not yet claimed
COMMAND_LIFECYCLE_CLAIMED - Command has been claimed by a service
COMMAND_LIFECYCLE_RUNNING - Command is currently executing
COMMAND_LIFECYCLE_COMPLETED - Command completed successfully
COMMAND_LIFECYCLE_FAILED - Command failed to execute
COMMAND_LIFECYCLE_CANCELLED - Command was cancelled

Stream Operations Copied

STREAM_OPERATION_UNSPECIFIED - Default/unspecified operation
STREAM_OPERATION_APPEND - Append to existing stream content
STREAM_OPERATION_REPLACE - Replace existing stream content

Validation Modes Copied

Used by RegisterCommands via validationMode:

VALIDATION_MODE_STRICT - Default. Rejects the entire request if any command fails validation. Also applied when validationMode is omitted
VALIDATION_MODE_LENIENT - Registers valid commands; invalid commands are not registered and are returned in rejected

Error Responses Copied

All endpoints may return a default error response using the Status schema.

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Common Error Status Codes Copied

400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists or conflict
500 Internal Server Error - Server error

Previous article Next article

Commands API

Command Registry Copied

Insert or update a single command definition Copied

Request Copied

Example Request Copied

Response Copied

Delete a command from a service Copied

Request Copied

Example Request Copied

Response Copied

Query configured commands for a target and/or service Copied

Request Copied

Example Request Copied

Response Copied

Register or replace all commands for a service Copied

Validation mode Copied

Batched registration and validation Copied

Request Copied

Example Request Copied

Response Copied

Retrieve a registered command service Copied

Request Copied

Example Request Copied

Response Copied

Command Execution Copied

Submit a command for execution Copied

Request Copied

Example Request Copied

Response Copied

Clear historical command execution entries Copied

Request Copied

Example Request Copied

Response Copied

Returns all triggered commands for a service Copied

Request Copied

Example Request Copied

Response Copied

Update the status of a command Copied

Request Copied

Example Request Copied

Response Copied

Query the status of one or more commands Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to triggered command status updates Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to triggered commands for a service Copied

Request Copied

Example Request Copied

Response Copied

Cancel a command execution Copied

Request Copied

Example Request Copied

Response Copied

Clear a historical command execution entry Copied

Request Copied

Example Request Copied

Response Copied

Subscribe to status updates for a specific command execution ID Copied

Request Copied

Example Request Copied

Response Copied

Extends the time-to-live of an executing command Copied

Request Copied

Example Request Copied

Response Copied

Permissions Copied

Replace the full set of command permissions for a service Copied

Request Copied

Example Request Copied

Response Copied

Delete command permissions for a service Copied

Request Copied

Example Request Copied

Response Copied

Query command permissions for a service Copied

Request Copied