NylorunDocsBeta
Runtime APISessions

Open a session

PUT
/v1/sessions/{sessionId}

Creates the session on an Agent, or answers the one already opened with the same Agent, owner, info and role. Its Agent (its sandbox and vault) is fixed for its life, and it pins the manifest version the Agent runs. role (Host feature model-roles) runs it on the model the version names for that role in harness.roles, checked as harness.model is; a role the version does not declare is 400 unknown_role. No session is special: an app that keeps one conversation going reuses its id.

Authorization

headerAuthorizationBearer <token>

An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).

Path Parameters

sessionId*string

Header Parameters

Nylorun-Protocol*string

The protocol version, 18

Nylorun-Subject?string

The person an application key acts for

Nylorun-Scopes?string

The subject's space-separated scopes; required with a subject

Request Body

application/json
  1. body
requestId*string
Length1 <= length
agent*string

An Agent id, such as triage or users/alice/triage

ownerUserId*string
Length1 <= length
info?
role?string

A model role's name, such as builder

Match^[a-z][a-z0-9-]{0,31}$

Response Body

The session

application/json
  1. response
id*string
agentId*string
ownerUserId*string
manifest*|null
manifestHash*string
status*string
Value in"idle""runnable""running""waiting""paused""uncertain""completed""failed""cancelled"
activeTurnId*string|null
queuedMessages*integer
Range0 <= value
harness*string
closedReason?string
mcpSnapshot*|null
mcpDiagnostics*array<>
model*|null
waits?unknown
error?string
uncertainEffects*array<>
import { createClient } from "@nylorun/agents";const client = await createClient();const session = await client.createSession({  agent: `users/${user.id}/assistant`, // the Agent the session runs on  ownerUserId: user.id,});
{  "id": "string",  "agentId": "string",  "ownerUserId": "string",  "manifest": {    "name": "string",    "version": 1  },  "manifestHash": "string",  "status": "idle",  "activeTurnId": "string",  "queuedMessages": 0,  "harness": "string",  "closedReason": "string",  "mcpSnapshot": {    "property1": null,    "property2": null  },  "mcpDiagnostics": [    {      "property1": null,      "property2": null    }  ],  "model": {    "provider": "string",    "model": "string",    "source": "manifest",    "role": "string",    "reason": "provider_not_connected",    "requested": {      "provider": "string",      "model": "string",      "by": "manifest"    }  },  "waits": null,  "error": "string",  "uncertainEffects": [    {      "effectId": "string",      "turnId": "string",      "kind": "string",      "error": null    }  ]}