Skip to content

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

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/steer

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

Parameters

Name Required Schema
runId Yes {"type":"string"}
text Yes schema.json#/$defs/NodeInstructions
mode No schema.json#/$defs/SteeringMode

Result

Name Schema
runSteerResult schema.json#/$defs/RunSteerResult

run/suspend

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

Parameters

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

Result

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

run/vectors

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

Parameters

Name Required Schema
runId Yes {"type":"string"}
after No schema.json#/$defs/RunVectorsParams/properties/after
limit No {"format":"uint32","maximum":100,"minimum":1,"type":["integer","null"]}

Result

Name Schema
runVectorsResult schema.json#/$defs/RunVectorsResult

inbox/list

Read-only vector-backed request inbox. Requires request_ask, kind openengine.request-ask/v1, in target discovery. Reads do not apply expiry or start a successor.

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

Parameters

Name Required Schema
after No {"type":["string","null"]}
limit No {"format":"uint32","maximum":100,"minimum":1,"type":["integer","null"]}

Result

Name Schema
inboxListResult schema.json#/$defs/InboxListResult

inbox/show

Read-only vector-backed request inbox. Requires request_ask, kind openengine.request-ask/v1, in target discovery. Reads do not apply expiry or start a successor.

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

Parameters

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

Result

Name Schema
inboxShowResult schema.json#/$defs/InboxShowResult

run/vector

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

Parameters

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

Result

Name Schema
runVectorResult schema.json#/$defs/RunVector

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 restarts a failed run where it started, on the latest retained workspace: a submitted run at its graph root, a successor at the boundary it began at, so an accepted answer stays accepted. 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. Checkpoint continuations and suspended successors restore captured node-instance provider conversations, and so does a restart of such a successor; the restart of a submitted run starts new ones. Suspended command/wait runs continue without restoring files. Request suspensions require from.kind answer with signals and output, or explicit expiry. Requests require request_ask (openengine.request-ask/v1); deadline expiry settles the held verifier with timeout.

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"]}
gitCredentials No {"anyOf":[{"$ref":"#/$defs/GitTransportCredentials"},{"type":"null"}],"description":"Fresh generic Git authority, excluded from immutable source and submission identity."}
commitIdentity No {"anyOf":[{"$ref":"#/$defs/CommitIdentity"},{"type":"null"}],"description":"Author and committer of every commit the successor's delivery creates. Omission keeps the\ntarget's default delivery identity."}
commitCoAuthor No {"anyOf":[{"$ref":"#/$defs/CommitIdentity"},{"type":"null"}],"description":"Person credited by a Co-authored-by trailer on every commit carrying the successor's\nchanges. Author and committer stay as commitIdentity selects."}

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