Deepnote Public API v2
Sessions API
Long-lived interactive sessions for running notebooks and blocks.
Base URL
https://api.deepnote.com/v2Create an interactive session
Creates an interactive session that runs the specified notebook and stays alive to accept further submissions. The session ends after a period of inactivity.
/sessionsRequest body
objectnotebookIdrequiredstringID of the source notebook the session is anchored to.
inputsobjectInput values for the initial run, keyed by input block `name`. Same shape as `POST /v2/runs`.
storageMode"read_write" | "readonly"Storage mode for the session. `read_write` (default) allows the session to write to project storage. `readonly` makes project storage read-only for the session; the session can still create temporary files.
Responses
▸202Session created with initial run
CreateSessionResponsesessionrequiredSessionrunrequiredobject▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions, or sessions are not enabled for this workspace
ErrorResponsemessagerequiredstring▸404Notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Hardware unable to start
ErrorResponsemessagerequiredstringExecute arbitrary code in a session kernel (debug)
Runs arbitrary code inside the notebook's kernel within an interactive session and returns the raw outputs (without creating a snapshot). User-code exceptions are returned as error outputs inside the response body and still produce HTTP 200.
/sessions/{sessionId}/executeParameters
sessionIdpathrequiredstring:uuidSession identifier.
Request body
objectnotebookIdrequiredstringSource notebook to execute against in the session.
coderequiredstringSource code to execute in the session sandbox.
timeoutMsintegerMaximum execution time in milliseconds. Must be a positive integer no greater than 120000. Values outside this range are rejected with 400; the server does not clamp. Defaults to 10000 when omitted.
Responses
▸200Outputs produced by the synchronous execution.
ExecuteSessionResponseoutputsrequiredJupyterOutput[]Raw Jupyter (nbformat) outputs produced by the synchronous execution. User-code exceptions are returned as `output_type: "error"` entries here, not as HTTP errors.
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions, or sessions are not enabled for this workspace
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸408Execution timed out
ErrorResponsemessagerequiredstring▸409Project is suspended, the notebook is busy with a tracked run, or the session kernel is unavailable
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringInterrupt active runs for a notebook in an interactive session
Interrupts active runs for the given notebook in an interactive session and signals the notebook kernel to stop any in-flight code, including arbitrary code submitted via `/sessions/{sessionId}/execute`. Other notebooks in the same session keep running, so the session may remain `busy`. Returns the refreshed session state.
/sessions/{sessionId}/interruptParameters
sessionIdpathrequiredstring:uuidSession identifier.
Request body
objectnotebookIdrequiredstringNotebook to interrupt within the session.
Responses
▸200Session state after the interrupt.
InterruptSessionResponsesessionrequiredSession▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions, or sessions are not enabled for this workspace
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringGet kernel status for a notebook in an interactive session
Returns the current kernel state for a notebook in an interactive session, including the currently executing block and queued block executions when available. Each notebook in a session has its own kernel; name the notebook via the `notebookId` query parameter and query each notebook separately.
/sessions/{sessionId}/statusParameters
sessionIdpathrequiredstring:uuidSession identifier.
notebookIdqueryrequiredstringNotebook within the session to read status for.
Responses
▸200Current session and kernel status for the notebook.
GetSessionNotebookStatusResponsesessionrequiredSessionkernelrequiredSessionKernelState▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions, or sessions are not enabled for this workspace
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring