Open a session
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.
AuthorizationBearer <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).
sessionId*stringNylorun-Protocol*stringThe protocol version, 18
Nylorun-Subject?stringThe person an application key acts for
Nylorun-Scopes?stringThe subject's space-separated scopes; required with a subject
application/json- body
requestId*string1 <= lengthagent*stringAn Agent id, such as triage or users/alice/triage
ownerUserId*string1 <= lengthinfo?role?stringA model role's name, such as builder
^[a-z][a-z0-9-]{0,31}$The session
application/json- response
id*stringagentId*stringownerUserId*stringmanifest*|nullmanifestHash*stringstatus*string"idle""runnable""running""waiting""paused""uncertain""completed""failed""cancelled"activeTurnId*string|nullqueuedMessages*integer0 <= valueharness*stringclosedReason?stringmcpSnapshot*|nullmcpDiagnostics*array<>model*|nullwaits?unknownerror?stringuncertainEffects*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 } ]}