sessions module route (requires sessions:run:write)

POST

/v1/m/sessions/runs

curl --request POST \
  --url https://example.com/v1/m/sessions/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "credentials": [ "example" ], "effort": "example", "env_allow": [ "example" ], "fast_mode": true, "git_read": "example", "isolation": "", "model": "example", "name": "example", "no_setup": true, "permission_mode": "", "provider_profile_ref": "example", "secret_env": [ { "env": "example", "secret": "example" } ], "service_tier": "example", "template_id": "example", "transport": "", "workspace_ref": "example", "worktree": true, "worktree_from": "example" }'

• this engine

Creates one session run from the posted parameters, and answers 503 when the runtime is not available.

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.

Request Body ^required

Media type application/json

Any of:

object

object

credentials

Any of:

Array<string>

Business. Names of managed credentials (an SSH key or certificate, a database login, an API account) the session gets a way to use: an SSH agent socket, a database proxy or a local reverse proxy that the engine holds, never the secret itself. Needs tenant administration. A Community engine answers 501 business_required.

Array<string>

<= 8 items unique items

null

null

effort

Any of:

string

Claude Code accepts low, medium, high, xhigh and max; other non-empty values return 400 even when its catalog lists them. This is the final Claude launch contract. Other drivers pass a bounded printable term to the tool. Empty/null keeps the tool default.

string

<= 64 characters

null

null

env_allow

Any of:

Array<string>

Array<string>

<= 64 items unique items

null

null

fast_mode

Any of:

boolean

Claude Code only. Explicit false turns Fast mode off; omitted/null keeps the tool default. True requires a catalog model that supports it and an own-account profile; provider-bound launches refuse it to preserve endpoint isolation.

boolean

null

null

git_read

Any of:

string

When non-empty, one approved Git-host repository binding (:/) the session gets a short-lived GitHub read credential for: an installation token with contents:read for that repository, served to git by a credential helper (never in the environment) and revoked when the session ends. Needs tenant administration. A GitLab binding is refused (422).

string

null

null

isolation

Any of:

string

Empty/null defaults to native; unavailable runners refuse rather than downgrade.

string

Allowed values: "" native container sandbox

null

null

model

Any of:

string

Trimmed before launch.

string

null

null

name

Any of:

string

Trimmed before persistence. At most 200 characters, with no control, invisible or separator characters; otherwise 400.

string

null

null

no_setup

Any of:

boolean

Skip the folder’s setup command for this start only; leaves its stored command and approval unchanged.

boolean

null

null

permission_mode

Any of:

string

Empty/null defaults to default.

string

Allowed values: "" default acceptEdits plan auto dontAsk bypassPermissions

null

null

provider_profile_ref

Any of:

string

When non-empty, names the provider profile the session launches under; the server resolves its homes and refuses a disabled, retired, foreign-environment or non-operable profile, and one whose driver requires an authorized authentication source it does not have. Only the reference is accepted: no home, environment, driver, binding, session id or authentication source.

string

null

null

secret_env

Any of:

Array<object>

Array<object>

<= 32 items

object

env

required

The environment variable the child reads the secret from. A shell name; variables the runtime, a provider or the host base owns are refused.

string

secret

required

The vault secret’s name in the tenant scope; must begin with env/.

string

null

null

service_tier

Any of:

string

Codex only. A non-empty, whitespace-free service tier is passed unchanged to thread/start and thread/resume; empty/null keeps the tool default. Other drivers refuse a non-empty choice.

string

<= 200 characters

null

null

template_id

Any of:

string

When non-empty, identifies the stored template whose terms govern the launch.

string

null

null

transport

Any of:

string

Empty/null defaults to stream-json.

string

Allowed values: "" stream-json remote-control

null

null

workspace_ref

Any of:

string

Trimmed and, when non-empty, resolved to a registered workspace.

string

null

null

worktree

Any of:

boolean

Opt in to a git worktree and a new branch of the session’s own, made from the named workspace’s repository (which must be the repository’s top folder, native isolation, with no read-only folders). Absent, null or false keeps the session in the workspace folder itself.

boolean

null

null

worktree_from

Any of:

string

With worktree: start the new worktree at this commit id or local branch of the workspace’s repository instead of its current commit (for example the branch and sha a handoff names). Absent keeps the current start. Refused without worktree, and when the commit or branch is not in the repository.

string

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

{}