Replaces the whole step graph atomically (write-tier, revisioned).

PUT

/v1/m/orchestration/workflows/{id}/steps

curl --request PUT \
  --url https://example.com/v1/m/orchestration/workflows/example/steps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "steps": [ { "config": { "schedule_id": "example" }, "depends_on": [ "example" ], "kind": "schedule-fire", "ref": "example" } ] }'

• this engine

Replaces the whole step graph atomically (write-tier, revisioned).

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Path parameter id.

Header Parameters

X-Olivares-Tenant

string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Request Body ^required

Media type application/json

Any of:

object

object

steps

Any of:

Array

The handler accepts an empty graph. Its configured step cap defaults to 50; refs must be unique, dependencies must exist, the graph must be acyclic, and fan-in/fan-out are capped at 8.

Array

One of:

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

schedule_id

required

Must identify an existing non-retired schedule.

string

>= 1 characters

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: schedule-fire

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

label

required

After trimming it must be non-empty and is byte-capped to 200.

string

>= 1 characters

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: eventing-emit

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

route_id

required

Must identify an existing notification route.

string

>= 1 characters

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: notify-test

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

seconds

required

integer format: int64

>= 1 <= 86400

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: wait

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

Any of:

object

object

reason

Any of:

string

Byte-capped to 200.

string

null

null

null

null

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: approval-gate

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

brief_md

required

string

>= 1 characters

brief_ref

Any of:

string

Exactly one of brief_md or brief_ref must be non-empty; maximum 512 bytes.

string

null

null

criteria

required

Keys and ordinals must be unique and at least one criterion must set required=true.

Array<object>

>= 1 items <= 16 items

object

key

required

Unique criterion key.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

ordinal

required

Must be unique within criteria.

integer format: int64

>= 1

required

Any of:

boolean

boolean

null

null

statement

required

After trimming it must be non-empty and no longer than 1024 bytes.

string

>= 1 characters

due_at

Any of:

string

When non-empty, must parse as a canonical timestamp.

string

null

null

owner

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

priority

required

string

Allowed values: p0 p1 p2 p3

provenance

required

object

hash

Any of:

string

When non-empty, it is byte-capped to 128.

string

null

null

kind

required

string

Allowed values: human workflow a2a mcp migration system

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

title

required

After trimming it must be non-empty and no longer than 256 bytes.

string

>= 1 characters

work_kind

required

Work kind slug.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

workspace_id

required

Must be a valid workspace identifier.

string

>= 1 characters

object

object

brief_md

Any of:

string

Exactly one of brief_md or brief_ref must be non-empty; maximum 2048 bytes.

string

null

null

brief_ref

required

string

>= 1 characters

criteria

required

Keys and ordinals must be unique and at least one criterion must set required=true.

Array<object>

>= 1 items <= 16 items

object

key

required

Unique criterion key.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

ordinal

required

Must be unique within criteria.

integer format: int64

>= 1

required

Any of:

boolean

boolean

null

null

statement

required

After trimming it must be non-empty and no longer than 1024 bytes.

string

>= 1 characters

due_at

Any of:

string

When non-empty, must parse as a canonical timestamp.

string

null

null

owner

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

priority

required

string

Allowed values: p0 p1 p2 p3

provenance

required

object

hash

Any of:

string

When non-empty, it is byte-capped to 128.

string

null

null

kind

required

string

Allowed values: human workflow a2a mcp migration system

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

title

required

After trimming it must be non-empty and no longer than 256 bytes.

string

>= 1 characters

work_kind

required

Work kind slug.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

workspace_id

required

Must be a valid workspace identifier.

string

>= 1 characters

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-create

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

When require_ack is false or absent, channel_id, context, context_ref, and ack_deadline must all be empty.

object

ack_deadline

Any of:

string

Required as a canonical timestamp when require_ack is true.

string

null

null

channel_id

Any of:

string

Required as a valid identifier when require_ack is true.

string

null

null

context

Any of:

string

With require_ack=true, exactly one of context or context_ref is required; maximum 2048 bytes.

string

null

null

context_ref

Any of:

string

With require_ack=true, exactly one of context or context_ref is required; maximum 512 bytes.

string

null

null

expected_owner_epoch

required

integer format: int64

>= 1

require_ack

Any of:

boolean

boolean

null

null

target

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-assign

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

sid

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

ttl_seconds

required

integer format: int64

>= 1 <= 86400

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-claim

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

attempt_kind

Any of:

string

Defaults to lease-bind when omitted or empty.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

fence

Any of:

integer

A positive literal fence is mutually exclusive with fence_step_ref.

integer format: int64

null

null

fence_step_ref

Any of:

string

Mutually exclusive with a positive literal fence.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

owner_epoch

Any of:

integer

integer format: int64

null

null

runtime_profile_ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: session-launch

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

ack_due_at

Any of:

string

When non-empty, must parse as a canonical timestamp.

string

null

null

body

required

string

>= 1 characters

body_ref

Any of:

string

Exactly one of body or body_ref must be non-empty; maximum 512 bytes.

string

null

null

channel_id

required

Must be a valid channel identifier.

string

>= 1 characters

recipient

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

urgency

Any of:

string

string

Allowed values: normal high critical

null

null

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

object

object

ack_due_at

Any of:

string

When non-empty, must parse as a canonical timestamp.

string

null

null

body

Any of:

string

Exactly one of body or body_ref must be non-empty; maximum 2048 bytes.

string

null

null

body_ref

required

string

>= 1 characters

channel_id

required

Must be a valid channel identifier.

string

>= 1 characters

recipient

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

urgency

Any of:

string

string

Allowed values: normal high critical

null

null

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-message

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

after_event_seq

Any of:

integer

integer format: int64

null

null

deadline

required

Must parse as a canonical timestamp.

string

>= 1 characters

target_id

required

string

/.*\S.*/

target_kind

required

string

Allowed values: message handoff

target_step_ref

Any of:

string

Exactly one of target_id or target_step_ref.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

object

object

after_event_seq

Any of:

integer

integer format: int64

null

null

deadline

required

Must parse as a canonical timestamp.

string

>= 1 characters

target_id

Any of:

string

Exactly one of target_id or target_step_ref; target_id must be a valid identifier.

string

null

null

target_kind

required

string

Allowed values: message handoff

target_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-wait-ack

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

ack_deadline

required

Must parse as a canonical timestamp.

string

>= 1 characters

channel_id

required

Must be a valid channel identifier.

string

>= 1 characters

context

required

string

>= 1 characters

context_ref

Any of:

string

Exactly one of context or context_ref must be non-empty; maximum 512 bytes.

string

null

null

target

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

object

object

ack_deadline

required

Must parse as a canonical timestamp.

string

>= 1 characters

channel_id

required

Must be a valid channel identifier.

string

>= 1 characters

context

Any of:

string

Exactly one of context or context_ref must be non-empty; maximum 2048 bytes.

string

null

null

context_ref

required

string

>= 1 characters

target

required

object

kind

required

string

Allowed values: user agent session

ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-handoff

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

evidence_ref

Any of:

string

When non-empty, maximum 512 bytes.

string

null

null

reason

Any of:

string

Required for blocked, failed, or canceled; when non-empty, maximum 2048 bytes.

string

null

null

target_state

required

string

Allowed values: ready blocked review completed failed canceled

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-transition

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

binding_id

Any of:

string

When non-empty, must be a valid binding identifier.

string

null

null

reason

required

After trimming it must be non-empty and no longer than 2048 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-cancel

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

binding_id

required

Must be a valid binding identifier.

string

>= 1 characters

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: work-reconcile

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

agent_ref

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

authority

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

binding_spec_generation

required

integer format: int64

>= 1

binding_spec_id

required

Must be a valid binding-spec identifier.

string

>= 1 characters

brief_hash

required

After trimming it must be non-empty and no longer than 128 bytes.

string

>= 1 characters

criteria_revision

required

integer format: int64

>= 1

lease_fence

required

integer format: int64

>= 1

owner_epoch

required

integer format: int64

>= 1

protocol

required

string

Allowed values: a2a mcp

protocol_version

required

After trimming it must be non-empty and no longer than 64 bytes.

string

>= 1 characters

scope

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

skill

required

After trimming it must be non-empty and no longer than 512 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

workspace_id

required

Must be a valid workspace identifier.

string

>= 1 characters

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: remote-plan

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

plan_step_ref

required

Must name the required upstream step.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: remote-test

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

object

plan_step_ref

required

Must name the required upstream step.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: remote-start

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

binding_id

required

string

/.*\S.*/

binding_step_ref

Any of:

string

Exactly one of binding_id or binding_step_ref.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

object

object

binding_id

Any of:

string

Exactly one of binding_id or binding_step_ref; binding_id must be a valid identifier.

string

null

null

binding_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: remote-observe

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

object

Config is strictly decoded, capped at 4096 JSON bytes, and canonicalized before storage.

object

config

required

One of:

object

object

binding_id

required

string

/.*\S.*/

binding_step_ref

Any of:

string

Exactly one of binding_id or binding_step_ref.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

reason

required

After trimming it must be non-empty and no longer than 2048 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

object

object

binding_id

Any of:

string

Exactly one of binding_id or binding_step_ref; binding_id must be a valid identifier.

string

null

null

binding_step_ref

required

string

/.*\S.*/

reason

required

After trimming it must be non-empty and no longer than 2048 bytes.

string

>= 1 characters

work_item_id

Any of:

string

A valid WorkItem identifier. Mutually exclusive with work_item_step_ref; omitting both selects the run root WorkItem.

string

null

null

work_item_step_ref

Any of:

string

A direct dependency that produces a WorkItem. Mutually exclusive with work_item_id.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

not matching

work_item_id

required

string

/.*\S.*/

work_item_step_ref

required

string

/.*\S.*/

depends_on

Any of:

Array<string>

Array<string>

<= 8 items unique items

null

null

kind

required

Allowed value: remote-cancel

ref

required

Unique within the workflow.

string

/^[a-z0-9][a-z0-9_-]{0,63}$/

null

null

null

null

Responses

200

OK

Media type application/json

object

Example ^generated

{}

400

Bad request

Media type application/json

object

Example ^generated

{}

401

Unauthenticated

Media type application/json

object

Example ^generated

{}

403

Forbidden

Media type application/json

object

Example ^generated

{}

404

Not found

Media type application/json

object

Example ^generated

{}

409

Conflict / setup required

Media type application/json

object

Example ^generated

{}

429

Rate limited

Media type application/json

object

Example ^generated

{}