---
title: "run.session-create-request@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/run.session-create-request"
updated: null
---

# run.session-create-request@1 · OpenVibe.Services

HTML: [run.session-create-request@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/run.session-create-request)

# RunSessionCreateRequest `run.session-create-request@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: run
- Visibility: public
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/run/session-create-request.v1.json`](/docs/contracts/run.session-create-request.json)

run.session-create-request@1 (the Desks plan's D6): the body of POST /api/v1/sessions on OpenVibe.Run (capability run.session.create), answered 201 with run.session@1 (state placing). The session is the caller's own: a person's token, or a first-party service acting for a person (X-OV-Subject; the service is recorded as via). MACHINE names one of the person's own machines (an OpenVibe.Bot device they own and let agents use): the session goes there or ends unplaceable, never elsewhere. Without it Run places the desk: on the person's own machines when REQUIREMENTS name user-owned (and only theirs), else on desk hosts that serve other people (first-party, then community, unless REQUIREMENTS narrow it), each of whose desks runs in its own sandbox. Absent REQUIREMENTS mean { kind: run.browser, mobility: session, latency\_class: interactive, objective: balanced }. TTL\_S (default 3600) and IDLE\_S (default 900) bound its life. IDEMPOTENCY\_KEY: a repeat from the same person within 24 h with an identical body answers the first session (200); with a different body 409 run.idempotency.conflict.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `kind` | const | yes |  | - `= "browser"` |
| `width` | `https://openvibe.network/contracts/run/session.v1.json#/$defs/size/properties/width` |  | Default 1280. |  |
| `height` | `https://openvibe.network/contracts/run/session.v1.json#/$defs/size/properties/height` |  | Default 800. |  |
| `ttl_s` | `https://openvibe.network/contracts/run/session.v1.json#/properties/ttl_s` |  | Default 3600. |  |
| `idle_s` | `https://openvibe.network/contracts/run/session.v1.json#/properties/idle_s` |  | Default 900. |  |
| `machine` | string |  | One of the person's own machines, by its OpenVibe.Bot id; the session goes there or nowhere. | - `pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$` |
| `origins` | array of string |  | Exact HTTP(S) origins allowed for this browser session. Run fixes the list at creation and places it only on a user-owned desk that can enforce it. This option is owner switched off by default. | - `maxItems 32`<br>- `items: pattern ^https?://`<br>- `items: minLength 8`<br>- `items: maxLength 2048` |
| `requirements` | [platform.workload-requirements](/docs/contracts/platform.workload-requirements) |  |  |  |
| `idempotency_key` | `https://openvibe.network/contracts/run/session.v1.json#/$defs/idempotency_key` |  |  |  |
| `task_id` | string |  | The OpenVibe.Actor task that asks for this session (plan 2026-11-07: one id across Surf, Computer and Actor). It is carried back on run.session@1, so the session and the task point at each other. | - `pattern ^tsk_[0-9A-HJKMNP-TV-Z]{26}$` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: community-only

~~~~
{
  "kind": "browser",
  "requirements": {
    "kind": "run.browser",
    "mobility": "session",
    "latency_class": "interactive",
    "objective": "cheapest",
    "trust": [
      "community"
    ]
  }
}
~~~~

Valid: default

~~~~
{
  "kind": "browser"
}
~~~~

Valid: own-machine

~~~~
{
  "kind": "browser",
  "width": 1440,
  "height": 900,
  "ttl_s": 1800,
  "idle_s": 600,
  "machine": "dev_01J8Z4M2Q0R7T9YV3K6N8P1W2X",
  "idempotency_key": "actor:tsk_01JD2C3D4E5F6G7H8J9K0MNPQR"
}
~~~~

Rejected: no-kind

~~~~
{
  "width": 1280
}
~~~~

Rejected: robot-id

~~~~
{
  "kind": "browser",
  "machine": "rob_01J8Z4M2Q0R7T9YV3K6N8P1W2X"
}
~~~~

Rejected: too-long

~~~~
{
  "kind": "browser",
  "ttl_s": 86400
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('run.session-create-request@1', value);   // { valid, errors: [{ path, message }] }
~~~~