Creates the carrier and WorkItem offer atomically without changing ownership.

POST

/v1/m/sessions/handoffs

curl --request POST \
  --url https://example.com/v1/m/sessions/handoffs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --header 'If-Match: example' \
  --data '{ "ack_deadline": "2026-04-15T12:00:00Z", "channel_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expected_owner_epoch": 1, "handoff": { "artifact_refs": [ { "hash": "example", "kind": "example", "ref": "example" } ], "branch": "example", "next_action": "example", "risk": "example", "sha": "example", "summary": "example" }, "recipient": { "kind": "user", "ref": "example" }, "work_item_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

• this engine

Creates the carrier and WorkItem offer atomically without changing ownership.

Authorizations

• bearerAuth
• browserSession

Parameters

Header Parameters

X-Olivares-Tenant

string format: uuid

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

If-Match

required

string

/^\"v[0-9]+\"$/

Current strong WorkItem ETag.

Idempotency-Key

required

string format: uuid

Canonical UUID binding the atomic offer and carrier creation.

Request Body ^required

Media type application/json

object

ack_deadline

required

string format: date-time

channel_id

required

string format: uuid

expected_owner_epoch

integer format: int64

handoff

required

object

artifact_refs

Array<object>

<= 64 items

object

hash

string

kind

required

string

>= 1 characters

ref

required

string

>= 1 characters

branch

Optional. The git branch the handed-over work is on. A label the sender wrote; the receiver may open a session worktree from it.

string

>= 1 characters <= 512 characters

next_action

required

string

>= 1 characters

risk

string

sha

Optional. The full git commit id the handed-over work is at (40 or 64 lowercase hex digits). The receiver may open a session worktree at it.

string

/^([0-9a-f]{40}|[0-9a-f]{64})$/

summary

required

string

>= 1 characters

recipient

required

object

kind

required

string

Allowed values: user agent session

ref

required

string

>= 1 characters <= 1024 characters

work_item_id

required

string format: uuid

Responses

200

Exact handoff offer receipt replay

Media type application/json

object

audit_seq

required

integer format: int64

command_id

required

string format: uuid

delivery_id

required

string format: uuid

etag

required

string

event_id

required

string format: uuid

handoff_id

required

string format: uuid

message_id

required

string format: uuid

replayed

required

boolean

state

required

string

version

required

integer format: int64

work_item_id

required

string format: uuid

Example ^generated

{
  "audit_seq": 1,
  "command_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "delivery_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "etag": "example",
  "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "handoff_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "message_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "replayed": true,
  "state": "example",
  "version": 1,
  "work_item_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

201

Handoff carrier and offer created

Media type application/json

object

audit_seq

required

integer format: int64

command_id

required

string format: uuid

delivery_id

required

string format: uuid

etag

required

string

event_id

required

string format: uuid

handoff_id

required

string format: uuid

message_id

required

string format: uuid

replayed

required

boolean

state

required

string

version

required

integer format: int64

work_item_id

required

string format: uuid

Example ^generated

{
  "audit_seq": 1,
  "command_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "delivery_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "etag": "example",
  "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "handoff_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "message_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "replayed": true,
  "state": "example",
  "version": 1,
  "work_item_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

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

Media type application/json

object

Example ^generated

{}

412

Precondition failed

Media type application/json

object

Example ^generated

{}

428

Required precondition missing

Media type application/json

object

Example ^generated

{}

429

Rate limited

Media type application/json

object

Example ^generated

{}

503

Current authority, custody or store evidence is unavailable; or, with code commit_outcome_unknown, the write was issued and its outcome was never learned, so it may be durable and must not be retried automatically

Media type application/json

object

Example ^generated

{}