NylorunDocsBeta
Runtime APISessions

Send a command to a session

POST
/v1/sessions/{sessionId}/commands

A message starts a turn, or waits in the session's queue while a turn runs or waits (protocol 17; delivery: "reject" is refused with 409 session_busy instead); the others answer what the session waits on, or cancel. Idempotent on the command's idempotencyKey.

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

traceparent?string

W3C trace context: the turn this request starts joins the caller's trace (feature traces). A malformed value is ignored

tracestate?string

W3C trace context, kept with traceparent

Request Body

application/json
  1. body
requestId*string
Length1 <= length
idempotencyKey*string
Length1 <= length <= 256
type*"message"
Value in"message"
manifest?
removeTools?array<>
Itemsitems <= 256
delivery?string
Value in"queue""reject""steer"
context?array<>
Items1 <= items <= 16
content*string
Length1 <= length

Response Body

The command, accepted; a message may be queued

application/json
  1. response
status*"accepted"
Value in"accepted"
turnId*string|null
cursor*string|null
requestId*string
import { createClient } from "@nylorun/agents";const client = await createClient();const session = client.session("ses_123");await session.input("Where is order demo-123?", {  idempotencyKey: crypto.randomUUID(),  delivery: "queue", // the default: waits for a running turn; "reject" is 409 session_busy});// Also: session.approve(), session.respond(), session.cancel()
{  "status": "accepted",  "turnId": "string",  "cursor": "string",  "requestId": "string"}