sessions module route (requires sessions:run:write)

POST

/v1/m/sessions/runs/{ref}/handoff

curl --request POST \
  --url https://example.com/v1/m/sessions/runs/example/handoff \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "provider_profile_ref": "example", "summary": "example" }'

• this engine

Starts a new session in the chosen provider profile, linked to one Claude Code, Codex, Gemini CLI or OpenCode session, from a reviewed summary and the attached transcript; a running session is stopped first and the answer says whether the first turn arrived.

Authorizations

• bearerAuth
• browserSession

Parameters

Path Parameters

ref

required

string

Path parameter ref.

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

object

name

The new session’s name. Defaults to a name that says it continues this one.

string

provider_profile_ref

required

The provider profile to continue in. It may belong to any tool, including the session’s own.

string

summary

The reviewed text the new session starts from. Omitted, the server generates it (GET /runs/{ref}/handoff returns the same text for review).

string

<= 65536 characters

Example ^generated

{
  "name": "example",
  "provider_profile_ref": "example",
  "summary": "example"
}

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

{}