API Reference

All Runner and Session communication uses NATS request-reply messaging. This document defines the complete set of endpoints, their request/response types, and the data transfer objects (DTOs) used on the wire.

Wire Format

All messages are JSON-serialized. Understanding how different types are encoded on the wire is essential for correct usage:

  • Object types (e.g., Image, SetSettingsRequest) are sent as JSON objects: {"Name": "...", "Packages": [...]}
  • String values are sent as JSON string literals. For example, SetTestPlanXML expects a JSON-encoded string containing the XML content. The XML must be wrapped in double quotes with proper JSON escaping: 
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<TestPlan type=\"OpenTap.TestPlan\">..."
  • Guid values are sent as JSON string literals in standard format: "a8a9baa6-d3b0-446d-a3e2-07bbf9310a71"
  • NoInput is sent as an empty JSON object: {}
  • NoResponse is returned as an empty JSON object: {}
  • Errors from the server are returned as NATS error responses with an OpenTapNatsError header. Fatal errors (e.g., invalid input, server exceptions) are communicated this way rather than in the response body.

Runner APIs

The {base} is in the form of: OpenTap.Runner.{RunnerId}.Request

Subject Request Type Response Type Available since
{base}.Status NoInput RunnerStatus v1.0
{base}.Shutdown NoInput NoResponse v1.0
{base}.GetImages NoInput List of Image v1.0
{base}.GetImage String Image v1.0
{base}.ResolveImage List of Image Image v1.0
{base}.ResolveImageDryRun List of Image Image v1.0
{base}.GetSessionManagerImage NoInput Image v1.0
{base}.GetSessions NoInput List of Session v1.0
{base}.StartSession NoInput Session v1.0
{base}.StartImageSession Image Session v1.0
{base}.StartDefaultSession RepositoryPackageReference Session v1.6
{base}.StartDefaultSessionOverrideImage DefaultSessionRequest Session v1.6
{base}.NewSession NewSessionRequest NewSessionResponse v2.2
{base}.SetSession Session Session v1.0
{base}.ShutdownSession Guid NoResponse v1.0
{base}.RegisterSession RegisterSessionRequest RegisterSessionResponse v1.0
{base}.SetDefaultSettings RepositoryPackageReference NoResponse v1.0
{base}.GetDefaultSettings NoInput RepositoryPackageReference v1.0
{base}.SaveDefaultSettingsInRepository SaveDefaultSettings NoResponse v1.0
{base}.GetDefaultImage NoInput Image v1.5
{base}.SetDefaultImage Image Image v1.5
{base}.UpdateRunner RunnerUpdateRequest RunnerUpdateResponse v1.4
{base}.LogsZip NoInput Byte[] v2.0
{base}.GetComponentSettingsOverview NoInput List of ComponentSettingsIdentifier v1.0
{base}.SetComponentSettings SetComponentSettingsRequest ComponentSettingsBase v1.0
{base}.GetComponentSettings GetComponentSettingsRequest ComponentSettingsBase v1.0
{base}.GetComponentSettingsListItem GetComponentSettingsListItemRequest ComponentSettingsListItem v1.0
{base}.SetComponentSettingsListItem SetComponentSettingsListItemRequest ComponentSettingsListItem v1.0
{base}.GetComponentSettingDataGrid GetComponentSettingDataGridRequest DataGridControl v1.0
{base}.SetComponentSettingDataGrid SetComponentSettingDataGridRequest DataGridControl v1.0
{base}.AddComponentSettingDataGridItemType AddComponentSettingDataGridItemTypeRequest DataGridControl v1.0
{base}.AddComponentSettingDataGridItem GetComponentSettingDataGridRequest DataGridControl v1.0
{base}.GetComponentSettingDataGridTypes GetComponentSettingDataGridRequest List of ListItemType v1.0
{base}.SetComponentSettingsProfiles List of ProfileGroup List of ProfileGroup v1.0
{base}.GetComponentSettingsProfiles NoInput List of ProfileGroup v1.0
{base}.UploadComponentSettings UploadFileRequest List of String v1.0
{base}.DownloadComponentSettings DownloadTapSettingsRequest Byte[] v1.0
{base}.LoadComponentSettingsFromRepository RepositoryPackageReference List of ErrorResponse v1.0
{base}.SaveComponentSettingsToRepository RepositorySettingsPackageDefinition NoResponse v1.0
{base}.GetComponentSettingsListAvailableTypes GetComponentSettingsRequest List of ListItemType v1.0
{base}.AddComponentSettingsListItem AddComponentSettingsListItemRequest ComponentSettingsBase v1.0
{base}.GetSettingsPackageFiles NoInput List of String v1.0
{base}.GetSettingsTypes NoInput List of String v1.0

Session APIs

The {base} is in the form of: OpenTap.Runner.{RunnerId}.Session.{SessionId}.Request

Subject Request Type Response Type Available since
{base}.GetStatus NoInput RunStatus v1.0
{base}.GetEditStatus NoInput EditStatus v2.0
{base}.GetTestPlanXML NoInput String v1.0
{base}.SetTestPlanXML String List of String v1.0
{base}.SetTestPlanName String NoResponse v1.0
{base}.GetTestPlanReference NoInput GetTestPlanReferenceResponse v1.0
{base}.LoadTestPlanFromRepository RepositoryPackageReference List of String v1.0
{base}.SaveTestPlanToRepository RepositoryPackageDefinition SaveTestPlanToRepositoryResponse v1.0
{base}.ResourcesOpen NoInput TestPlan v1.0
{base}.ResourcesClose NoInput TestPlan v1.0
{base}.GetSettings GetSettingsRequest Settings v1.0
{base}.SetSettings SetSettingsRequest Settings v1.0
{base}.GetTestPlan String[] TestPlan v1.0
{base}.SetTestPlan TestPlan TestPlan v1.0
{base}.MoveSteps MoveRequest NoResponse v2.0
{base}.MoveStepsAsChildren MoveRequest NoResponse v2.0
{base}.DeleteSteps DeleteRequest NoResponse v2.0
{base}.GetValidationErrors NoInput TestPlanValidationErrors v1.0
{base}.CommonStepSettings CommonSettings CommonSettings v1.0
{base}.CommonStepSettingsContextMenu CommonStepSettingsContext CommonContext v1.0
{base}.GetUserInputs NoInput List of Guid v1.0
{base}.GetUserInput Guid Interaction v1.0
{base}.SetUserInput Interaction Interaction v1.0
{base}.GetContextMenu PropertyReferenceRequest List of Setting v1.0
{base}.SetContextMenu SetContextMenuRequest List of Setting v1.0
{base}.GetDataGrid PropertyReferenceRequest DataGridControl v1.0
{base}.SetDataGrid SetDataGridRequest DataGridControl v1.0
{base}.AddDataGridItemType AddDataGridItemTypeRequest DataGridControl v1.0
{base}.AddDataGridItem PropertyReferenceRequest DataGridControl v1.0
{base}.GetDataGridTypes PropertyReferenceRequest List of ListItemType v1.0
{base}.GetStepTypes NoInput List of TestStepType v1.0
{base}.CopySteps CopyRequest String v2.0
{base}.PasteSteps PasteRequest NoResponse v2.0
{base}.PasteStepsAsChildren PasteRequest NoResponse v2.0
{base}.RunTestPlan List of Parameter RunStatus v1.0
{base}.SetPauseNext NoInput NoResponse v1.0
{base}.GetBreakpoints NoInput BreakPoints v1.0
{base}.SetBreakpoints BreakPoints BreakPoints v1.0
{base}.SetJumpToStep Guid NoResponse v1.0
{base}.AbortTestPlan NoInput NoResponse v1.0
{base}.TestPlanUndo NoInput NoResponse v2.0
{base}.TestPlanRedo NoInput NoResponse v2.0
{base}.GetSessionLogs GetSessionLogsRequest LogList v1.0
{base}.SessionLogSearch GetSessionSearchRequest List of Int32 v1.0
{base}.SessionLogSources NoInput List of String v1.0
{base}.SessionLogCounts NoInput Dictionary of Int32 to Int32 v1.0
{base}.LogLevels NoInput Dictionary of Int32 to String v1.0
{base}.SetupMetricsPolling EnableMetricsPollingRequest EnableMetricsPollingResponse v2.0
{base}.DiscoverAssets NoInput AssetDiscoveryResponse v2.0
{base}.GetComponentSettingsOverview NoInput List of ComponentSettingsIdentifier v1.0
{base}.SetComponentSettings SetComponentSettingsRequest ComponentSettingsBase v1.0
{base}.GetComponentSettings GetComponentSettingsRequest ComponentSettingsBase v1.0
{base}.GetComponentSettingsListItem GetComponentSettingsListItemRequest ComponentSettingsListItem v1.0
{base}.SetComponentSettingsListItem SetComponentSettingsListItemRequest ComponentSettingsListItem v1.0
{base}.GetComponentSettingDataGrid GetComponentSettingDataGridRequest DataGridControl v1.0
{base}.SetComponentSettingDataGrid SetComponentSettingDataGridRequest DataGridControl v1.0
{base}.AddComponentSettingDataGridItemType AddComponentSettingDataGridItemTypeRequest DataGridControl v1.0
{base}.AddComponentSettingDataGridItem GetComponentSettingDataGridRequest DataGridControl v1.0
{base}.GetComponentSettingDataGridTypes GetComponentSettingDataGridRequest List of ListItemType v1.0
{base}.SetComponentSettingsProfiles List of ProfileGroup List of ProfileGroup v1.0
{base}.GetComponentSettingsProfiles NoInput List of ProfileGroup v1.0
{base}.UploadComponentSettings UploadFileRequest List of String v1.0
{base}.DownloadComponentSettings DownloadTapSettingsRequest Byte[] v1.0
{base}.LoadComponentSettingsFromRepository RepositoryPackageReference List of ErrorResponse v1.0
{base}.SaveComponentSettingsToRepository RepositorySettingsPackageDefinition NoResponse v1.0
{base}.GetComponentSettingsListAvailableTypes GetComponentSettingsRequest List of ListItemType v1.0
{base}.AddComponentSettingsListItem AddComponentSettingsListItemRequest ComponentSettingsBase v1.0
{base}.GetSettingsPackageFiles NoInput List of String v1.0
{base}.GetSettingsTypes NoInput List of String v1.0
{base}.Shutdown NoInput NoResponse v1.0
{base}.GetImage NoInput Image v1.0
{base}.SetWatchDog WatchDog WatchDog v1.0
{base}.GetWatchDog NoInput WatchDog v1.0

Endpoint Details

SetTestPlanXML

The String request for SetTestPlanXML must contain valid OpenTAP test plan XML (.TapPlan format). The XML content is JSON-encoded as a string literal on the wire (see Wire Format).

The List of String response contains non-fatal deserialization warnings from the OpenTAP serializer. For example, a missing plugin type or a package version mismatch will appear as a string in this list. An empty list means the test plan loaded without issues.

Fatal errors (e.g., invalid XML, corrupt data, or a test plan already executing) are returned as NATS error responses, not in the response body.

Example using the NATS CLI:

nats req OpenTap.Runner.{RunnerId}.Session.{SessionId}.Request.SetTestPlanXML '"<?xml version=\"1.0\" encoding=\"utf-8\"?><TestPlan type=\"OpenTap.TestPlan\"><Steps /></TestPlan>"'

Data Types

NoInput

Empty JSON object {}.

For example, the Session endpoint to abort a test plan takes a NoInput:

nats req OpenTap.Runner.{RunnerId}.Session.{SessionId}.Request.AbortTestPlan "{}"

NoResponse

Empty JSON object {}.

For example, the Session endpoint to abort a test plan returns a NoResponse:

nats req OpenTap.Runner.{RunnerId}.Session.{SessionId}.Request.AbortTestPlan "{}" returns {}.

RunnerStatus

Property Type
RemoteConnection RemoteConnection
Version String
RunningAsService Boolean
RunningInContainer Boolean
AutoUpdateDisabled Boolean
AllowParallelRuns Boolean
Hostname String
IpAddress String
StreamInfo StreamInfoStatus

RemoteConnection

Property Type
Endpoint String
Connected Boolean
Rtt String

StreamInfoStatus

Property Type
RunsMaxBytes Int64
RunsUsage Int64
DiskFree Int64

Image

Property Type
Name String
Packages List of PackageSpecifier
Repositories List of String
Id String

Session

Property Type
Subject String
Id Guid
ImageId String
SessionState SessionState
TestPlanRunId String
StartedBy String
Metadata Dictionary of String to String

SessionState

Enum with the following values:

  • Idle
  • Loading
  • Executing
  • Breaking
  • Aborting
  • WaitingForUserInput

RunStatus

Property Type
SessionId Guid
Verdict Verdict
TestPlanRunId Guid (nullable)
FailedToStart Boolean
SessionState SessionState
ExecutingSteps List of Guid

EditStatus

Property Type
TestPlanDirty Boolean
UndoBufferSize Int32
RedoBufferSize Int32

ErrorResponse

Returned by endpoints such as LoadComponentSettingsFromRepository. Represents a structured error with optional nested inner errors.

Property Type
Type String
Message String
Parameter String (nullable)
Source String (nullable)
StackTrace String (nullable)
Inner ErrorResponse (nullable)

NewSessionRequest

Property Type
Image Image
UseDefaults Boolean
ImageOverride Image
TestPlanReference RepositoryPackageReference
Settings Settings
RunTestPlan Boolean
TestPlanParameters List of Parameter
ShutdownOnComplete Boolean
Metadata Dictionary of String to String

NewSessionResponse

Property Type
Session Session

DefaultSessionRequest

Property Type
ImageOverride Image
TestPlanReference RepositoryPackageReference

RegisterSessionRequest

Property Type
SessionId Guid
ProcessId Int32
ExpectedRunnerVersion String
Operator String
Metadata Dictionary of String to String

RegisterSessionResponse

Property Type
Success Boolean
Message String
Url String
AccessToken String
OperatorId String
SettingsFileLocation String
TestPlan RepositoryPackageReference
Settings Settings
RunTestPlan Boolean
Parameters List of Parameter
ShutdownOnComplete Boolean

SaveDefaultSettings

Property Type
SessionId Guid
Repository String

Note: Repository is accepted by the client library for forward-compatibility but is currently ignored by the server.

RunnerUpdateRequest

Property Type
UpdateTo String

RunnerUpdateResponse

Property Type
Success Boolean
ErrorMessage String

GetSettingsRequest

Property Type
ContextId Guid

GetTestPlanReferenceResponse

Property Type
TestPlanReference RepositoryPackageReference

SaveTestPlanToRepositoryResponse

Property Type
TestPlanReference RepositoryPackageReference

MoveRequest

Property Type
StepIds List of Guid
TargetStepId Guid

DeleteRequest

Property Type
StepIds List of Guid

Parameter

Property Type
Group String
Name String
Value String
TypeCode TypeCode

EnableMetricsPollingRequest

Property Type
Enabled Boolean

EnableMetricsPollingResponse

Property Type
JetStreamName String
Enabled Boolean

AssetDiscoveryResponse

Property Type
AssetProviders List of AssetDiscoveryResult
LastSeen DateTime

AssetDiscoveryResult

Property Type
DiscoveredAssets List of DiscoveredAsset
Priority Double
Name String
IsSuccess Boolean
Error String

DiscoveredAsset

Property Type
Manufacturer String
Model String
AssetIdentifier String

SetComponentSettingsRequest

Property Type
ReturnedSettings ComponentSettingsBase
GroupName String
Name String

ComponentSettingsBase

Property Type
Name String
GroupName String

ComponentSettingsIdentifier

Extends ComponentSettingsBase. Returned by GetComponentSettingsOverview to identify available component settings without loading their full configuration.

Property Type
Name String
GroupName String

GetComponentSettingsRequest

Property Type
GroupName String
Name String

GetComponentSettingsListItemRequest

Property Type
Index Int32
GroupName String
Name String

ComponentSettingsListItem

Property Type
Settings Settings
Name String
EnabledResource Boolean (nullable)
VisualStatus VisualStatus
ValueType String
UnitAttribute UnitAttribute
Display DisplayAttribute
MetaData MetaData
ExternalParameter ExternalParameter

SetComponentSettingsListItemRequest

Property Type
Item ComponentSettingsListItem
Index Int32
GroupName String
Name String

GetComponentSettingDataGridRequest

Property Type
PropertyName String
Index Int32
GroupName String
Name String

DataGridControl

Property Type
Items List of List of Setting
FixedSize Boolean
Errors List of String
Layout Layout
ColumnDisplayName ColumnDisplayName
ValueDescription String
PropertyName String
Icons List of Icon
Submit Boolean
VisualStatus VisualStatus
ValueType String
UnitAttribute UnitAttribute
Display DisplayAttribute
MetaData MetaData
ExternalParameter ExternalParameter

SetComponentSettingDataGridRequest

Property Type
DataGridControl DataGridControl
PropertyName String
Index Int32
GroupName String
Name String

AddComponentSettingDataGridItemTypeRequest

Property Type
TypeName String
PropertyName String
Index Int32
GroupName String
Name String

UploadFileRequest

Property Type
File Byte[]
FileName String

DownloadTapSettingsRequest

Property Type
GroupName String

RepositoryPackageReference

Property Type
Version String
Path String
PathId String

RepositorySettingsPackageDefinition

Property Type
Name String
Tags List of String
Version String
Path String
PathId String

AddComponentSettingsListItemRequest

Property Type
TypeName String
GroupName String
Name String

CopyRequest

Property Type
StepIds List of Guid

PasteRequest

Property Type
TargetStepId Guid
Clipboard String

PackageSpecifier

Property Type
Name String
Version String
Architecture String
OS String

Settings

A JSON array of Setting objects. Serialized as [{...}, {...}, ...].

VisualStatus

Property Type
IsReadOnly Boolean
IsVisible Boolean
IsEnabled Boolean

UnitAttribute

Property Type
Unit String
PreScaling Double
StringFormat String
UseRanges Boolean
UseEngineeringPrefix Boolean

DisplayAttribute

Property Type
Description String
Group List of String
Name String
Order Double
Collapsed Boolean

MetaData

Property Type
Name String
MacroName String
Group String
Frozen Boolean

ExternalParameter

Property Type
Name String

Layout

Property Type
Mode LayoutMode
RowHeight Int32
MaxRowHeight Int32

ListItemType

Represents a selectable type in a component settings list or data grid.

Property Type
TypeName String
TypeDisplay DisplayAttribute

ColumnDisplayName

Property Type
ColumnName String
Order Double
IsReadOnly Boolean

Icon

Property Type
IconName String
Invoke Boolean (nullable)
StepReference Guid (nullable)
PropertyReference String

Setting

Property Type
Errors List of String
Layout Layout
ColumnDisplayName ColumnDisplayName
ValueDescription String
PropertyName String
Icons List of Icon
Submit Boolean
VisualStatus VisualStatus
ValueType String
UnitAttribute UnitAttribute
Display DisplayAttribute
MetaData MetaData
ExternalParameter ExternalParameter

RepositoryPackageDefinition

Property Type
Name String
Tags List of String
Version String
Path String
PathId String

TestPlan

Property Type
ChildTestSteps List of TestStep
Settings Settings
IsOpen Boolean
PropertiesToInclude List of String
Id Guid

SetSettingsRequest

Property Type
ContextId Guid
Settings Settings

TestPlanValidationErrors

A JSON array of TestStepValidationError objects.

CommonSettings

Property Type
Step TestStep
StepIds List of Guid

CommonStepSettingsContext

Property Type
CommonContext CommonContext
PropertyName String

CommonContext

Property Type
ContextItems List of Setting
StepIds List of Guid

Interaction

Property Type
Timeout String
Title String
Modal Boolean
Settings Settings
Id Guid

PropertyReferenceRequest

Property Type
ContextId Guid
PropertyName String

ProfileGroup

Represents a group of component settings profiles.

Property Type
Profiles List of String
CurrentProfile String
GroupName String

SetContextMenuRequest

Property Type
ContextId Guid
PropertyName String
ContextMenu List of Setting

SetDataGridRequest

Property Type
ContextId Guid
PropertyName String
DataGridControl DataGridControl

AddDataGridItemTypeRequest

Property Type
ContextId Guid
PropertyName String
TypeName String

BreakPoints

Property Type
TestSteps List of Guid

GetSessionLogsRequest

Property Type
Levels List of Int32
ExcludedSources List of String
FilterText String
Offset Int32
Limit Int32

LogList

Property Type
Logs List of LogEntry
Offset Int32
FilteredCount Int32
TotalCount Dictionary of String to Int32

GetSessionSearchRequest

Property Type
Levels List of Int32
ExcludedSources List of String
FilterText String
SearchText String

WatchDog

Property Type
InactiveSeconds Double
TerminationTimeout Int32

TestStep

Property Type
Id Guid
ChildTestSteps List of TestStep
IsChildTestStepsReadOnly Boolean
IsReadOnly Boolean
Settings Settings
TypeName String
TypeDisplay DisplayAttribute
Name String
ExpandedName String

TestStepType

Extends TestStep. Returned by GetStepTypes to describe an available test step type and its allowed children.

Property Type
Id Guid
ChildTestSteps List of TestStep
IsChildTestStepsReadOnly Boolean
IsReadOnly Boolean
Settings Settings
TypeName String
TypeDisplay DisplayAttribute
Name String
ExpandedName String
AvailableChildrenTypes List of String

TestStepValidationError

Property Type
StepId String
ValidationErrors List of ValidationError

LogEntry

Property Type
Source String
Timestamp Int64
Message String
Level Int32
DurationNS Int64

ValidationError

Property Type
PropertyName String
Error String

Verdict

Outcome of a test plan run. Serialized as a PascalCase string.

Value Integer
NotSet 0
Pass 1
Inconclusive 2
Fail 3
Aborted 4
Error 5

SlimSession

Compact session summary included in runner heartbeat events.

Property Type
SessionId Guid
SessionState SessionState

LayoutMode

Flags enum controlling UI layout of a setting. Values can be combined (bitwise OR).

Value Integer
Normal 1
FullRow 2
FloatBottom 4

TypeCode

Maps to System.TypeCode. Indicates the primitive type of a Parameter value. Serialized as a PascalCase string.

Value Integer
Empty 0
Object 1
DBNull 2
Boolean 3
Char 4
SByte 5
Byte 6
Int16 7
UInt16 8
Int32 9
UInt32 10
Int64 11
UInt64 12
Single 13
Double 14
Decimal 15
DateTime 16
String 18