Open Engine Cluster Protocol API reference

Protocol version 1.0.0, described by OpenRPC 1.3.2.

This page is generated from the checked-in OpenRPC document. Method names, parameters, results, and transport capabilities below are projections of that document.

Machine-readable definitions

• OpenRPC document
• Protocol schema
• Graph schema
• Compiled graph IR schema
• Worker schema
• Run observation schema

Generic subscription framing

watch, logs, and agent/attach each establish a subscription through one JSON-RPC result. run/watch, run/logs, and run/attach use the same framing. The connection layer establishes all six subscriptions; Dispatcher::dispatch alone cannot answer them. After establishment, every subscription uses the generic notification methods below. No method-specific event, cancel, or closed names exist on the wire: watch/event, watch/cancel, watch/closed, logs/event, logs/cancel, logs/closed, agent/attach/event, agent/attach/cancel, and agent/attach/closed are not methods. $/cancelRequest asks the transport to cancel an in-flight unary request by its RequestId. An unknown or already-completed ID is ignored, and cancellation makes no rollback claim after backend state commits.

Notification	Schema
$/cancelRequest	schema.json#/$defs/CancelRequestParams
event	schema.json#/$defs/EventNotification
subscription/cancel	schema.json#/$defs/SubscriptionCancelParams
subscription/closed	schema.json#/$defs/SubscriptionClosedNotification

Methods

initialize

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
protocolVersion	Yes	{"const":"openengine.cluster/v1","type":"string"}

Result

Name	Schema
initializeResult	schema.json#/$defs/InitializeResult

plan

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
graph	Yes	schema.json#/$defs/GraphSpec

Result

Name	Schema
planResult	schema.json#/$defs/PlanResult

apply

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
graph	Yes	schema.json#/$defs/GraphSpec
input	No	true
dryRun	No	{"default":false,"type":"boolean"}
ifGeneration	No	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
idempotencyKey	No	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
applyResult	schema.json#/$defs/ApplyResult

update

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
labels	No	schema.json#/$defs/Labels
logLevel	No	schema.json#/$defs/LogLevel
suspended	No	{"type":"boolean"}
ifGeneration	Yes	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
idempotencyKey	Yes	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
updateResult	schema.json#/$defs/UpdateResult

stop

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
mode	Yes	schema.json#/$defs/StopMode
ifGeneration	Yes	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
idempotencyKey	Yes	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
stopResult	schema.json#/$defs/StopResult

retry

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
ifGeneration	Yes	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
idempotencyKey	Yes	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
retryResult	schema.json#/$defs/RetryResult

resubmit

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
ifGeneration	Yes	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
ifRunId	Yes	{"type":"string"}
idempotencyKey	Yes	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}
replacementInput	No	true

Result

Name	Schema
resubmitResult	schema.json#/$defs/ResubmitResult

delete

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
ifGeneration	Yes	{"maximum":9007199254740991,"minimum":0,"type":"integer"}
ifRunId	No	{"type":["string","null"]}
idempotencyKey	Yes	{"maxLength":256,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
deleteResult	schema.json#/$defs/DeleteResult

get

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
atCursor	No	{"type":["string","null"]}

Result

Name	Schema
getResult	schema.json#/$defs/GetResult

watch

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

Name	Required	Schema
runId	No	{"type":["string","null"]}
fromCursor	No	{"type":["string","null"]}

Result

Name	Schema
watchResult	schema.json#/$defs/WatchResult

logs

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

This method has no parameters.

Result

Name	Schema
logsResult	schema.json#/$defs/LogsResult

agent/attach

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

Name	Required	Schema
execution	Yes	{"maxLength":128,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
agentAttachResult	schema.json#/$defs/AgentAttachResult

run/submit

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
submission	Yes	schema.json#/$defs/RunSubmission

Result

Name	Schema
runSubmitResult	schema.json#/$defs/RunSubmitResult

run/list

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

This method has no parameters.

Result

Name	Schema
runListResult	schema.json#/$defs/RunListResult

run/status

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}

Result

Name	Schema
runStatusResult	schema.json#/$defs/RunStatusResult

run/watch

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
fromCursor	No	{"type":["string","null"]}

Result

Name	Schema
runWatchResult	schema.json#/$defs/RunWatchResult

run/logs

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
fromCursor	No	{"type":["string","null"]}
execution	No	{"maxLength":128,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":["string","null"]}

Result

Name	Schema
runLogsResult	schema.json#/$defs/RunLogsResult

run/attach

Parameter structure	Transport	Server push	Inbound notifications
by-name	Subscription	Yes	Yes

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
execution	Yes	{"maxLength":128,"minLength":1,"pattern":"^[^\u0000-\u001f\u007f-\u009f]+$","type":"string"}

Result

Name	Schema
runAttachResult	schema.json#/$defs/RunAttachResult

run/force

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}

Result

Name	Schema
runForceResult	schema.json#/$defs/RunForceResult

run/checkpoints

Lists checkpoints in increasing sequence order. The after cursor is exclusive. Omitted limit means 50; accepted limits are 1 through 100. Concurrent groups, including every map wave and nested child, expose one entry point. Storage and execution seeds remain private to the target.

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
after	No	{"anyOf":[{"$ref":"#/$defs/CheckpointId"},{"type":"null"}]}
limit	No	{"format":"uint32","maximum":100,"minimum":1,"type":["integer","null"]}

Result

Name	Schema
runCheckpointsResult	schema.json#/$defs/RunCheckpointsResult

run/resume

Omitting from or selecting restart starts the graph at its root on the latest retained workspace. Selecting checkpoint restores the matching workspace and predecessor outputs and reruns the named node or atomic concurrent group. Original admission and delivery metadata remain fixed. Credentials are resolved again for the successor; provider sessions are not resumed.

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}
successorRunId	Yes	{"type":"string"}
from	No	{"anyOf":[{"$ref":"#/$defs/RunResumeFrom"},{"type":"null"}],"description":"Omission preserves restarting from the latest retained workspace."}
connections	No	{"additionalProperties":false,"description":"Fresh static connection values for the successor attempt.","patternProperties":{"^[^\u0000-\u001f\u007f-\u009f]+$":{"$ref":"#/$defs/StaticConnectionValues"}},"type":"object"}
connectionResolver	No	{"anyOf":[{"$ref":"#/$defs/TargetConnectionResolver"},{"type":"null"}],"description":"Run-scoped callback used to resolve fresh dynamic connection values."}
githubToken	No	{"description":"Fresh GitHub credential for private source checkout or Git delivery.","type":["string","null"]}

Result

Name	Schema
runResumeResult	schema.json#/$defs/RunResumeResult

run/discard_workspace

Parameter structure	Transport	Server push	Inbound notifications
by-name	Unary	No	No

Parameters

Name	Required	Schema
runId	Yes	{"type":"string"}

Result

Name	Schema
runDiscardWorkspaceResult	schema.json#/$defs/RunDiscardWorkspaceResult