Notebook endpoints

The REST endpoints behind a Shell notebook tab. The admin console calls them; you can call them from a script to run cells in a kernel without the UI. All of them are under /api/notebook/ and need a system administrator's session token. The ones that start, run, stop or close a kernel need an administrator who can write. See the REST API reference for the header.

A kernel belongs to the administrator who opened it. A session ID from another administrator behaves as if the kernel did not exist.

Method and route	Reads or writes	Description
`POST /api/notebook/open`	Writes	Starts a kernel and returns its session ID.
`POST /api/notebook/run`	Writes	Runs one cell in a kernel.
`POST /api/notebook/interrupt?sessionID=`	Writes	Stops the cell that is running.
`POST /api/notebook/close?sessionID=`	Writes	Ends a kernel.
`POST /api/notebook/variables?sessionID=`	Reads	Lists the variables the cells defined.
`POST /api/notebook/complete`	Reads	Completions for a position in some code.

A request without a body, where one is expected, returns 400.

Open

POST /api/notebook/open

Field	Type	Description
`Language`	number	`0` for C#, `1` for Python.
`Sandbox`	boolean	`true` runs the kernel in the sandboxed shell scope: a read-only graph, as the Shell's Sandbox toggle.

Returns { "SessionID": "…" }. An administrator can have 8 kernels open; a ninth returns 429 with the text Too many notebooks are open. Close one first. A kernel that receives no request for 30 minutes ends.

curl -s -X POST "$HOST/api/notebook/open" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"Language": 1, "Sandbox": false}'

Run

POST /api/notebook/run

Field	Type	Description
`SessionID`	string	From `open`.
`Code`	string	The cell's source.

A cell that fails still returns 200; Succeeded is false and the error is in Outputs. The code is written to the audit log and the server log, as a Shell run is. One cell runs at a time in a kernel: a second run waits for the first.

Returns:

Field	Type	Description
`SessionFound`	boolean	`false` when the kernel no longer exists (ended, or another administrator's). The cell did not run; open a new kernel.
`ExecutionCount`	number	The cell's number in this kernel.
`Succeeded`	boolean	Whether the cell ran to its end.
`ElapsedMs`	number	How long the cell took, in milliseconds.
`Outputs`	array	What the cell produced, in the order it happened.

Each output has:

Field	Type	Description
`Kind`	string	`stream` (printed text), `display`, `result` (the last expression), or `error`.
`StreamName`	string	`stdout` or `stderr`, for a stream.
`ErrorName`	string	The exception type, for an error: `ZeroDivisionError`, `KeyboardInterrupt`.
`Data`	object	The output as a bundle: a map from a MIME type to its text. `text/plain` is always there.

The MIME types a bundle can hold are text/plain, text/html, text/markdown, image/svg+xml, image/png and image/jpeg (base64), application/json, and application/vnd.flint+json for a chart.

curl -s -X POST "$HOST/api/notebook/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"SessionID": "0ad0de7c1d9444be9b296d9c945d90f9", "Code": "xs = [1, 2, 3]\nprint(\"hi\")\nsum(xs)"}'

{
  "SessionFound": true,
  "ExecutionCount": 1,
  "Succeeded": true,
  "ElapsedMs": 23,
  "Outputs": [
    { "Kind": "stream", "StreamName": "stdout", "ErrorName": null, "Data": { "text/plain": "hi\n" } },
    { "Kind": "result", "StreamName": null, "ErrorName": null, "Data": { "text/plain": "6" } }
  ]
}

A cell that ends in a query returns it as application/json beside its text/plain; a cell that ends in a chart returns application/vnd.flint+json.

Interrupt

POST /api/notebook/interrupt?sessionID=<id>

Cancels the CancellationToken of the scope for the cell that is running. The kernel and its variables stay. The running run request returns with Succeeded: false: KeyboardInterrupt in Python, The cell was interrupted. in C#. Returns 200, also when nothing is running.

Close

POST /api/notebook/close?sessionID=<id>

Ends the kernel and releases what it holds. Returns 200, also when the kernel is already gone.

Variables

POST /api/notebook/variables?sessionID=<id>

Returns an array of { "Name", "Type", "Summary" }. Summary is a short text form, at most 80 characters. A Python kernel leaves out modules, names starting with _, and the names the notebook set up itself (the shell module and flint). A kernel that does not exist returns an empty array.

Complete

POST /api/notebook/complete

Field	Type	Description
`SessionID`	string	From `open`.
`Code`	string	The cell's source up to and after the caret.
`Cursor`	number	The caret's offset into `Code`.

Returns { "Items": [ … ], "Start": n }: the candidate names, sorted and at most 200, and the offset in Code where the word being completed starts. A Python kernel completes names in scope, members of modules and members of objects, and follows call chains on the scope by their declared types; it never runs your code. A C# kernel returns no items from this endpoint: the editor completes C# through the Shell's own completion endpoints.

curl -s -X POST "$HOST/api/notebook/complete" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"SessionID": "0ad0de7c1d9444be9b296d9c945d90f9", "Code": "q().start_at(\"Ticket\").em", "Cursor": 25}'