API reference sections

HTTP API reference

Terminal sessions

Process sessions: create and terminate, controller lease, input, snapshots, scrollback, attachments and output.

19 operations. The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

List session metadata

GET/v1/sessions

Query fields use the typed request schema in x-koru-request-schema.

Authorization: Bearer token with sessions.metadata.read
Operation id: sessions.list

Request fields (in the query)

ListSessionsRequest

Field	Type	Description
parent_session_id	TerminalSessionId or null

Responses

Status	Description	Body
200	List session metadata	SessionList
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "sessions": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "parent_session_id": "00000000-0000-4000-8000-000000000000",
      "profile": {
        "kind": "built_in",
        "value": "string"
      },
      "display_name": "string",
      "working_directory": "string",
      "mode": {
        "kind": "raw_pty"
      },
      "process": {
        "kind": "starting"
      },
      "controller": "detached",
      "managed": "idle",
      "active_turn_id": "00000000-0000-4000-8000-000000000000",
      "attention": {
        "unread_count": 0,
        "requires_user": false,
        "reason": "background_output"
      },
      "pending_attachment_count": 0,
      "capabilities": [],
      "project_id": "00000000-0000-4000-8000-000000000000",
      "handover": "idle",
      "model": {
        "requested": "string",
        "reported": "string"
      },
      "origin": {
        "kind": "manual"
      },
      "created_at_ms": 0
    }
  ]
}

Behavior

Required capability: sessions
Request fields in: query
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl "http://127.0.0.1:$PORT/v1/sessions" \
  -H "Authorization: Bearer $KORU_TOKEN"

Create a rooted process session

POST/v1/sessions

Authorization: Bearer token with sessions.control
Operation id: sessions.create

Request fields (in the body)

CreateSessionRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
profilerequired	SessionProfileKey	Stable identity for a launch profile. Built-ins remain readable across machines; user-created profiles are opaque UUIDs.
parent_session_id	TerminalSessionId or null
mode	SessionMode	Raw remains the compatibility default. Managed creation is accepted only for a profile whose provider passes the rooted host handshake. Default `{"kind":"raw_pty"}`
working_directoryrequired	string	An absolute local path. The Agent-owned host validates it at spawn.
sizerequired	GridSize

Request body (required)

application/json CreateSessionRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
profilerequired	SessionProfileKey	Stable identity for a launch profile. Built-ins remain readable across machines; user-created profiles are opaque UUIDs.
parent_session_id	TerminalSessionId or null
mode	SessionMode	Raw remains the compatibility default. Managed creation is accepted only for a profile whose provider passes the rooted host handshake. Default `{"kind":"raw_pty"}`
working_directoryrequired	string	An absolute local path. The Agent-owned host validates it at spawn.
sizerequired	GridSize

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "profile": {
    "kind": "built_in",
    "value": "string"
  },
  "parent_session_id": "00000000-0000-4000-8000-000000000000",
  "mode": {
    "kind": "raw_pty"
  },
  "working_directory": "string",
  "size": {
    "columns": 0,
    "rows": 0
  }
}

Responses

Status	Description	Body
200	Create a rooted process session	SessionSummary
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "parent_session_id": "00000000-0000-4000-8000-000000000000",
  "profile": {
    "kind": "built_in",
    "value": "string"
  },
  "display_name": "string",
  "working_directory": "string",
  "mode": {
    "kind": "raw_pty"
  },
  "process": {
    "kind": "starting"
  },
  "controller": "detached",
  "managed": "idle",
  "active_turn_id": "00000000-0000-4000-8000-000000000000",
  "attention": {
    "unread_count": 0,
    "requires_user": false,
    "reason": "background_output"
  },
  "pending_attachment_count": 0,
  "capabilities": [],
  "project_id": "00000000-0000-4000-8000-000000000000",
  "handover": "idle",
  "model": {
    "requested": "string",
    "reported": "string"
  },
  "origin": {
    "kind": "manual"
  },
  "created_at_ms": 0
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: No
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "profile": {
    "kind": "built_in",
    "value": "string"
  },
  "parent_session_id": "00000000-0000-4000-8000-000000000000",
  "mode": {
    "kind": "raw_pty"
  },
  "working_directory": "string",
  "size": {
    "columns": 0,
    "rows": 0
  }
}'

Get one session's metadata

GET/v1/sessions/{session_id}

Authorization: Bearer token with sessions.metadata.read
Operation id: sessions.get

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the none)

EmptyRequest

Type EmptyRequest

Responses

Status	Description	Body
200	Get one session's metadata	SessionSummary
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "parent_session_id": "00000000-0000-4000-8000-000000000000",
  "profile": {
    "kind": "built_in",
    "value": "string"
  },
  "display_name": "string",
  "working_directory": "string",
  "mode": {
    "kind": "raw_pty"
  },
  "process": {
    "kind": "starting"
  },
  "controller": "detached",
  "managed": "idle",
  "active_turn_id": "00000000-0000-4000-8000-000000000000",
  "attention": {
    "unread_count": 0,
    "requires_user": false,
    "reason": "background_output"
  },
  "pending_attachment_count": 0,
  "capabilities": [],
  "project_id": "00000000-0000-4000-8000-000000000000",
  "handover": "idle",
  "model": {
    "requested": "string",
    "reported": "string"
  },
  "origin": {
    "kind": "manual"
  },
  "created_at_ms": 0
}

Behavior

Required capability: sessions
Request fields in: none
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $KORU_TOKEN"

Terminate the complete process tree

DELETE/v1/sessions/{session_id}

Authorization: Bearer token with sessions.controlsessions.terminate
Operation id: sessions.terminate

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

TerminateRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken

Request body (required)

application/json TerminateRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}

Responses

Status	Description	Body
200	Terminate the complete process tree	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X DELETE "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}'

Acquire the exclusive controller lease

POST/v1/sessions/{session_id}/controller

Authorization: Bearer token with sessions.control
Operation id: sessions.attach

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

AttachSessionRequest

Field	Type	Description
viewport_generationrequired	ViewportGeneration
columnsrequired	integer (uint16, >= 0, <= 65535)
overscan_rowsrequired	integer (uint16, >= 0, <= 65535)

Request body (required)

application/json AttachSessionRequest

Field	Type	Description
viewport_generationrequired	ViewportGeneration
columnsrequired	integer (uint16, >= 0, <= 65535)
overscan_rowsrequired	integer (uint16, >= 0, <= 65535)

Example request body

{
  "viewport_generation": 1,
  "columns": 0,
  "overscan_rows": 0
}

Responses

Status	Description	Body
200	Acquire the exclusive controller lease	ControllerLease
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "token": "00000000-0000-4000-8000-000000000000",
  "granted_at_ms": 0
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: No

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/controller" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "viewport_generation": 1,
  "columns": 0,
  "overscan_rows": 0
}'

Release the controller lease without ending the process

DELETE/v1/sessions/{session_id}/controller

Authorization: Bearer token with sessions.control
Operation id: sessions.detach

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

DetachSessionRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken

Request body (required)

application/json DetachSessionRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken

Example request body

{
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}

Responses

Status	Description	Body
200	Release the controller lease without ending the process	EmptyResponse
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: No
Safe to retry after an unknown outcome: No

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X DELETE "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/controller" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}'

Read a bounded terminal snapshot

POST/v1/sessions/{session_id}/snapshot

Authorization: Bearer token with sessions.output.read
Operation id: sessions.snapshot

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

SnapshotRequest

Field	Type	Description
viewport_generationrequired	ViewportGeneration
rangerequired	RowRange
columnsrequired	integer (uint16, >= 0, <= 65535)

Request body (required)

application/json SnapshotRequest

Field	Type	Description
viewport_generationrequired	ViewportGeneration
rangerequired	RowRange
columnsrequired	integer (uint16, >= 0, <= 65535)

Example request body

{
  "viewport_generation": 1,
  "range": {
    "first": 0,
    "count": 0
  },
  "columns": 0
}

Responses

Status	Description	Body
200	Read a bounded terminal snapshot	SnapshotResponse
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "snapshot": {
    "session_id": "00000000-0000-4000-8000-000000000000",
    "terminal_generation": 1,
    "viewport_generation": 1,
    "sequence": {},
    "viewport": {
      "first": 0,
      "count": 0
    },
    "size": {
      "columns": 0,
      "rows": 0
    },
    "rows": [
      {
        "index": 0,
        "cells": [
          {
            "column": 0,
            "text": "string",
            "width": "zero",
            "style": {
              "foreground": {
                "kind": "default_foreground"
              },
              "background": {
                "kind": "default_foreground"
              },
              "bold": false,
              "dim": false,
              "italic": false,
              "underline": false,
              "strikeout": false,
              "inverse": false
            }
          }
        ],
        "wrapped_to_next": false
      }
    ],
    "cursor": {
      "row": 0,
      "column": 0,
      "shape": "block",
      "blinking": false
    },
    "modes": {
      "alternate_screen": false,
      "application_cursor": false,
      "bracketed_paste": false,
      "mouse_reporting": false,
      "mouse_tracking": "off",
      "mouse_encoding": "legacy",
      "focus_reporting": false,
      "origin_mode": false,
      "auto_wrap": false
    },
    "attention": {
      "unread_count": 0,
      "requires_user": false,
      "reason": "background_output"
    }
  },
  "resume": {
    "after_event": 1,
    "after_output": 1
  }
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/snapshot" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "viewport_generation": 1,
  "range": {
    "first": 0,
    "count": 0
  },
  "columns": 0
}'

Read one bounded scrollback page

POST/v1/sessions/{session_id}/scrollback

Authorization: Bearer token with sessions.output.read
Operation id: sessions.scrollback

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

ScrollbackRequest

Field	Type	Description
terminal_generationrequired	TerminalGeneration
viewport_generationrequired	ViewportGeneration
rangerequired	RowRange

Request body (required)

application/json ScrollbackRequest

Field	Type	Description
terminal_generationrequired	TerminalGeneration
viewport_generationrequired	ViewportGeneration
rangerequired	RowRange

Example request body

{
  "terminal_generation": 1,
  "viewport_generation": 1,
  "range": {
    "first": 0,
    "count": 0
  }
}

Responses

Status	Description	Body
200	Read one bounded scrollback page	ScrollbackResponse
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "page": {
    "session_id": "00000000-0000-4000-8000-000000000000",
    "terminal_generation": 1,
    "viewport_generation": 1,
    "sequence": 1,
    "range": {
      "first": 0,
      "count": 0
    },
    "rows": [
      {
        "index": 0,
        "cells": [
          {
            "column": 0,
            "text": "string",
            "width": "zero",
            "style": {
              "foreground": {
                "kind": "default_foreground"
              },
              "background": {
                "kind": "default_foreground"
              },
              "bold": false,
              "dim": false,
              "italic": false,
              "underline": false,
              "strikeout": false,
              "inverse": false
            }
          }
        ],
        "wrapped_to_next": false
      }
    ],
    "has_earlier": false,
    "has_later": false
  }
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/scrollback" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "terminal_generation": 1,
  "viewport_generation": 1,
  "range": {
    "first": 0,
    "count": 0
  }
}'

Write base64-encoded bytes to the process

POST/v1/sessions/{session_id}/input/bytes

Authorization: Bearer token with sessions.control
Operation id: sessions.write_bytes

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

WriteBytesRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
data_base64required	string	Base64-encoded process bytes. Access logs never record this value.

Request body (required)

application/json WriteBytesRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
data_base64required	string	Base64-encoded process bytes. Access logs never record this value.

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "data_base64": "string"
}

Responses

Status	Description	Body
200	Write base64-encoded bytes to the process	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/input/bytes" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "data_base64": "string"
}'

Write text to the process

POST/v1/sessions/{session_id}/input/text

Authorization: Bearer token with sessions.control
Operation id: sessions.write_text

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

WriteTextRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string

Request body (required)

application/json WriteTextRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string"
}

Responses

Status	Description	Body
200	Write text to the process	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/input/text" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string"
}'

Send one terminal key

POST/v1/sessions/{session_id}/input/key

Authorization: Bearer token with sessions.control
Operation id: sessions.send_key

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

SendKeyRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
keyrequired	KeyStroke

Request body (required)

application/json SendKeyRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
keyrequired	KeyStroke

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "key": {
    "key": {
      "text": "string",
      "kind": "character"
    },
    "modifiers": {
      "shift": false,
      "control": false,
      "alt": false,
      "primary": false
    }
  }
}

Responses

Status	Description	Body
200	Send one terminal key	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/input/key" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "key": {
    "key": {
      "text": "string",
      "kind": "character"
    },
    "modifiers": {
      "shift": false,
      "control": false,
      "alt": false,
      "primary": false
    }
  }
}'

Paste text using terminal paste semantics

POST/v1/sessions/{session_id}/input/paste

Authorization: Bearer token with sessions.control
Operation id: sessions.paste

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

PasteTextRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string

Request body (required)

application/json PasteTextRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string"
}

Responses

Status	Description	Body
200	Paste text using terminal paste semantics	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/input/paste" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string"
}'

List session-owned attachments

GET/v1/sessions/{session_id}/attachments

Authorization: Bearer token with sessions.attachments.write
Operation id: sessions.list_attachments

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the none)

EmptyRequest

Type EmptyRequest

Responses

Status	Description	Body
200	List session-owned attachments	AttachmentList
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "attachments": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "session_id": "00000000-0000-4000-8000-000000000000",
      "kind": "image",
      "source": "clipboard",
      "media_type": "string",
      "byte_count": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "status": {
        "kind": "ingesting"
      },
      "delivery_mode": "native_structured",
      "delivery": {
        "kind": "pending"
      },
      "turn_id": "00000000-0000-4000-8000-000000000000",
      "preview_available": false,
      "created_at_ms": 0
    }
  ]
}

Behavior

Required capability: sessions
Request fields in: none
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $KORU_TOKEN"

Upload and attach verified image bytes

POST/v1/sessions/{session_id}/attachments

Authorization: Bearer token with sessions.controlsessions.attachments.write
Operation id: sessions.upload_attachment

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

UploadAttachmentRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken
attachment_idrequired	AttachmentId
data_base64required	string	Base64-encoded image bytes. Media type and extension are detected from the decoded bytes; the public caller supplies neither a path nor a name.

Request body (required)

application/json UploadAttachmentRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken
attachment_idrequired	AttachmentId
data_base64required	string	Base64-encoded image bytes. Media type and extension are detected from the decoded bytes; the public caller supplies neither a path nor a name.

Example request body

{
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "attachment_id": "00000000-0000-4000-8000-000000000000",
  "data_base64": "string"
}

Responses

Status	Description	Body
200	Upload and attach verified image bytes	Attachment
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "session_id": "00000000-0000-4000-8000-000000000000",
  "kind": "image",
  "source": "clipboard",
  "media_type": "string",
  "byte_count": 0,
  "dimensions": {
    "width": 0,
    "height": 0
  },
  "status": {
    "kind": "ingesting"
  },
  "delivery_mode": "native_structured",
  "delivery": {
    "kind": "pending"
  },
  "turn_id": "00000000-0000-4000-8000-000000000000",
  "preview_available": false,
  "created_at_ms": 0
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "attachment_id": "00000000-0000-4000-8000-000000000000",
  "data_base64": "string"
}'

Remove one pending attachment

DELETE/v1/sessions/{session_id}/attachments/{attachment_id}

Authorization: Bearer token with sessions.controlsessions.attachments.write
Operation id: sessions.remove_attachment

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId
attachment_idrequired	path	AttachmentId

Request fields (in the body)

RemoveAttachmentRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken

Request body (required)

application/json RemoveAttachmentRequest

Field	Type	Description
controller_leaserequired	ControllerLeaseToken

Example request body

{
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}

Responses

Status	Description	Body
200	Remove one pending attachment	Attachment
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "session_id": "00000000-0000-4000-8000-000000000000",
  "kind": "image",
  "source": "clipboard",
  "media_type": "string",
  "byte_count": 0,
  "dimensions": {
    "width": 0,
    "height": 0
  },
  "status": {
    "kind": "ingesting"
  },
  "delivery_mode": "native_structured",
  "delivery": {
    "kind": "pending"
  },
  "turn_id": "00000000-0000-4000-8000-000000000000",
  "preview_available": false,
  "created_at_ms": 0
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: No
Safe to retry after an unknown outcome: No

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X DELETE "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}'

Deliver one logical text-and-attachment input

POST/v1/sessions/{session_id}/pending-input

Authorization: Bearer token with sessions.controlsessions.attachments.write
Operation id: sessions.send_pending_input

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

SendPendingInputRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string
attachment_idsrequired	array of AttachmentId	Ordered by the caller composing this logical input.
references	array of PathReference

Request body (required)

application/json SendPendingInputRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
textrequired	string
attachment_idsrequired	array of AttachmentId	Ordered by the caller composing this logical input.
references	array of PathReference

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string",
  "attachment_ids": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "references": [
    {
      "kind": "file",
      "path": "string"
    }
  ]
}

Responses

Status	Description	Body
200	Deliver one logical text-and-attachment input	SendPendingInputResult
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "turn_id": "00000000-0000-4000-8000-000000000000",
  "attachments": [
    {
      "attachment_id": "00000000-0000-4000-8000-000000000000",
      "mode": "native_structured",
      "state": {
        "kind": "pending"
      }
    }
  ]
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/pending-input" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "text": "string",
  "attachment_ids": [
    "00000000-0000-4000-8000-000000000000"
  ],
  "references": [
    {
      "kind": "file",
      "path": "string"
    }
  ]
}'

Interrupt the active process

POST/v1/sessions/{session_id}/interrupt

Authorization: Bearer token with sessions.control
Operation id: sessions.interrupt

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

InterruptRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken

Request body (required)

application/json InterruptRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}

Responses

Status	Description	Body
200	Interrupt the active process	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/interrupt" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000"
}'

Set the process terminal size

PUT/v1/sessions/{session_id}/size

Authorization: Bearer token with sessions.control
Operation id: sessions.resize

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the body)

ResizeRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
sizerequired	GridSize

Request body (required)

application/json ResizeRequest

Field	Type	Description
idempotency_keyrequired	IdempotencyKey
controller_leaserequired	ControllerLeaseToken
sizerequired	GridSize

Example request body

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "size": {
    "columns": 0,
    "rows": 0
  }
}

Responses

Status	Description	Body
200	Set the process terminal size	CommandReceipt
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Example 200 response

{
  "idempotency_key": "00000000-0000-4000-8000-000000000000"
}

Behavior

Required capability: sessions
Request fields in: body
Controller lease required: Yes
Idempotency key required: Yes
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl -X PUT "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/size" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "00000000-0000-4000-8000-000000000000",
  "controller_lease": "00000000-0000-4000-8000-000000000000",
  "size": {
    "columns": 0,
    "rows": 0
  }
}'

GET/v1/sessions/{session_id}/subscribe

Query fields use the typed request schema in x-koru-request-schema.

Authorization: Bearer token with sessions.output.read
Operation id: sessions.subscribe

Parameters

Name	In	Type	Description
session_idrequired	path	TerminalSessionId

Request fields (in the query)

SubscribeRequest

Field	Type	Description
after_event	StreamSequence or null	Last event sequence the caller consumed. Event and raw-output counters are independent and therefore cannot share one cursor.
after_output	StreamSequence or null	Last raw-output sequence the caller consumed.

Responses

Status	Description	Body
200	Subscribe to ordered output and lifecycle events	SessionStreamItemtext/event-stream
400	A stable machine-readable Koru failure	Failure
401	A stable machine-readable Koru failure	Failure
403	A stable machine-readable Koru failure	Failure
404	A stable machine-readable Koru failure	Failure
409	A stable machine-readable Koru failure	Failure
422	A stable machine-readable Koru failure	Failure
500	A stable machine-readable Koru failure	Failure
503	A stable machine-readable Koru failure	Failure
504	A stable machine-readable Koru failure	Failure

Behavior

Required capability: sessions
Request fields in: query
Controller lease required: No
Idempotency key required: No
Safe to retry after an unknown outcome: Yes

Error code	HTTP status
session.invalid_request	400
session.conflict	409
session.not_found	404
session.unavailable	503
session.unsupported	422
session.forbidden	403
session.internal	500
unauthenticated	401
permission_denied	403
capability_unavailable	503
gateway_saturated	503
deadline_exceeded	504
server_unavailable	503

Example request

curl "http://127.0.0.1:$PORT/v1/sessions/$SESSION_ID/subscribe" \
  -N \
  -H "Authorization: Bearer $KORU_TOKEN"

Streaming API reference (AsyncAPI) Some operations here answer with a stream. The streaming reference documents the AsyncAPI channels and their messages.

Generated from contract version 1. Last updated November 12, 2026.