A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
components:
schemas:
ActiveLineNotification:
description: "Reports the line a cell's frame watcher is currently executing.\n\
\n Emitted on a timed heartbeat while a cell runs (only when the line\n\
\ changed), so the editor can highlight the live line. A `None` line\n\
\ clears the highlight (e.g. when the cell finishes).\n\n Attributes:\n\
\ cell_id: Cell whose frame is being watched.\n line: 1-based\
\ line within the cell, or `None` to clear."
properties:
cell_id:
$ref: '#/components/schemas/CellId'
line:
anyOf:
- type: integer
- type: 'null'
default: null
op:
enum:
- active-line
required:
- op
- cell_id
title: ActiveLineNotification
type: object
AddPackageRequest:
description: 'This can be a remove package or a local package.
Supported formats:
httpx
httpx==0.27.0
httpx>=0.27.0
git+https://github.com/encode/httpx
https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz
/example/foo-0.1.0-py3-none-any.whl'
properties:
group:
anyOf:
- type: string
- type: 'null'
default: null
package:
type: string
upgrade:
anyOf:
- type: boolean
- type: 'null'
default: false
required:
- package
title: AddPackageRequest
type: object
AiCompletionContext:
properties:
plainText:
default: ''
type: string
schema:
default: []
items:
$ref: '#/components/schemas/SchemaTable'
type: array
variables:
default: []
items:
anyOf:
- type: string
- $ref: '#/components/schemas/VariableContext'
type: array
required: []
title: AiCompletionContext
type: object
AiCompletionRequest:
description: 'UIMessages are expected to be AI SDK messages.
See pydantic_ai.ui.vercel_ai.request_types.UIMessage or Vercel AI SDK documentation.'
properties:
code:
type: string
context:
anyOf:
- $ref: '#/components/schemas/AiCompletionContext'
- type: 'null'
default: null
id:
anyOf:
- type: string
- type: 'null'
default: null
includeOtherCode:
type: string
language:
default: python
enum:
- markdown
- python
- sql
prompt:
type: string
selectedText:
anyOf:
- type: string
- type: 'null'
default: null
uiMessages:
default: []
items:
type: object
type: array
required:
- prompt
- includeOtherCode
- code
title: AiCompletionRequest
type: object
AiConfig:
description: "Configuration options for AI.\n\n **Keys.**\n\n - `enabled`:\
\ if `False`, hide AI actions and panels in the marimo UI\n - `rules`:\
\ custom rules to include in all AI completion prompts\n - `max_tokens`:\
\ the maximum number of tokens to use in AI completions\n - `mode`: notebook\
\ access for the built-in assistant: `\"ask\"` (read only), `\"agent\"` (suggest\
\ edits), or `\"code_mode\"` (full access). Defaults to `\"ask\"`.\n -\
\ `inline_tooltip`: if `True`, enable inline AI tooltip suggestions\n -\
\ `allow_provider_config`: if `False`, lock provider setup in the settings\
\ UI, making them read-only. Users cannot bring their own credentials or add\
\ custom providers. Default `True`.\n - `models`: the models to use for\
\ AI completions\n - `open_ai`: the OpenAI config\n - `anthropic`: the\
\ Anthropic config\n - `google`: the Google AI config\n - `bedrock`:\
\ the Bedrock config\n - `azure`: the Azure config\n - `ollama`: the\
\ Ollama config\n - `github`: the GitHub Copilot config\n - `openrouter`:\
\ the OpenRouter config\n - `wandb`: the Weights & Biases config\n -\
\ `opencode_go`: the OpenCode Go config\n - `custom_providers`: a dict\
\ of custom OpenAI-compatible providers\n - `open_ai_compatible`: the OpenAI-compatible\
\ config (deprecated, use custom_providers)"
properties:
allow_provider_config:
type: boolean
anthropic:
$ref: '#/components/schemas/AnthropicConfig'
azure:
$ref: '#/components/schemas/OpenAiConfig'
bedrock:
$ref: '#/components/schemas/BedrockConfig'
custom_providers:
additionalProperties:
$ref: '#/components/schemas/OpenAiConfig'
type: object
enabled:
type: boolean
github:
$ref: '#/components/schemas/GitHubConfig'
google:
$ref: '#/components/schemas/GoogleAiConfig'
inline_tooltip:
type: boolean
max_tokens:
type: integer
mode:
enum:
- agent
- ask
- code_mode
- manual
models:
$ref: '#/components/schemas/AiModelConfig'
ollama:
$ref: '#/components/schemas/OpenAiConfig'
open_ai:
$ref: '#/components/schemas/OpenAiConfig'
open_ai_compatible:
$ref: '#/components/schemas/OpenAiConfig'
opencode_go:
$ref: '#/components/schemas/OpenAiConfig'
openrouter:
$ref: '#/components/schemas/OpenAiConfig'
rules:
type: string
wandb:
$ref: '#/components/schemas/OpenAiConfig'
required: []
title: AiConfig
type: object
AiInlineCompletionRequest:
properties:
language:
default: python
enum:
- markdown
- python
- sql
prefix:
type: string
suffix:
type: string
required:
- prefix
- suffix
title: AiInlineCompletionRequest
type: object
AiModelConfig:
description: "Configuration options for an AI model.\n\n **Keys.**\n\n \
\ - `chat_model`: the model to use for chat completions\n - `edit_model`:\
\ the model to use for edit completions\n - `autocomplete_model`: the model\
\ to use for code completion/autocomplete\n - `displayed_models`: a list\
\ of models to display in the UI\n - `custom_models`: a list of custom\
\ models to use that are not from the default list"
properties:
autocomplete_model:
type: string
chat_model:
type: string
custom_models:
items:
type: string
type: array
displayed_models:
items:
type: string
type: array
edit_model:
type: string
required:
- custom_models
- displayed_models
title: AiModelConfig
type: object
AlertNotification:
description: "User-facing alert message.\n\n Attributes:\n title:\
\ Alert title.\n description: Alert body (may contain HTML).\n \
\ variant: Visual variant (e.g., \"danger\")."
properties:
description:
type: string
op:
enum:
- alert
title:
type: string
variant:
anyOf:
- enum:
- danger
- type: 'null'
default: null
required:
- op
- title
- description
title: AlertNotification
type: object
AnthropicConfig:
description: "Configuration options for Anthropic.\n\n **Keys.**\n\n -\
\ `api_key`: the Anthropic API key or an `env:` reference"
properties:
api_key:
type: string
required: []
title: AnthropicConfig
type: object
AutoExportAsIPYNBRequest:
properties:
download:
type: boolean
required:
- download
title: AutoExportAsIPYNBRequest
type: object
AutoExportAsMarkdownRequest:
properties:
download:
type: boolean
required:
- download
title: AutoExportAsMarkdownRequest
type: object
BannerNotification:
description: "Persistent banner message at top of notebook.\n\n Attributes:\n\
\ title: Banner title.\n description: Banner body (may contain\
\ HTML).\n variant: Visual variant (e.g., \"danger\").\n action:\
\ Optional user action (e.g., \"restart\")."
properties:
action:
anyOf:
- enum:
- restart
- type: 'null'
default: null
description:
type: string
op:
enum:
- banner
title:
type: string
variant:
anyOf:
- enum:
- danger
- type: 'null'
default: null
required:
- op
- title
- description
title: BannerNotification
type: object
Base64String:
contentEncoding: base64
format: base64
type: string
BaseResponse:
properties:
success:
type: boolean
required:
- success
title: BaseResponse
type: object
BasedpyrightServerConfig:
description: 'Configuration options for basedpyright Language Server.
basedpyright handles completion, hover, go-to-definition, and diagnostics,
but we only use it for diagnostics.'
properties:
enabled:
type: boolean
required: []
title: BasedpyrightServerConfig
type: object
BedrockConfig:
description: "Configuration options for Bedrock.\n\n **Keys.**\n\n - `profile_name`:\
\ the AWS profile to use\n - `region_name`: the AWS region to use\n \
\ - `aws_access_key_id`: the AWS access key ID\n - `aws_secret_access_key`:\
\ the AWS secret access key"
properties:
aws_access_key_id:
type: string
aws_secret_access_key:
type: string
profile_name:
type: string
region_name:
type: string
required: []
title: BedrockConfig
type: object
CacheClearedNotification:
description: "Execution cache cleared result.\n\n Attributes:\n bytes_freed:\
\ Bytes freed by clearing cache."
properties:
bytes_freed:
type: integer
op:
enum:
- cache-cleared
required:
- op
- bytes_freed
title: CacheClearedNotification
type: object
CacheConfig:
description: "Configuration for caching.\n\n `verification` is the signature-checking\
\ posture; `store` is the backing\n store, or a list of stores composed\
\ into a `TieredStore`; `loader` is the\n default `method` for `mo.persistent_cache`."
properties:
loader:
anyOf:
- enum:
- json
- lazy
- pickle
- type: string
store:
anyOf:
- items:
$ref: '#/components/schemas/StoreConfig'
type: array
- $ref: '#/components/schemas/StoreConfig'
verification:
enum:
- 'off'
- 'on'
- strict
required: []
title: CacheConfig
type: object
CacheInfoNotification:
description: "Execution cache statistics.\n\n Attributes:\n hits:\
\ Cache hits.\n misses: Cache misses.\n time: Time spent on\
\ cache operations (seconds).\n disk_to_free: Disk space that could\
\ be freed (bytes).\n disk_total: Total disk space used (bytes)."
properties:
disk_to_free:
type: integer
disk_total:
type: integer
hits:
type: integer
misses:
type: integer
op:
enum:
- cache-info
time:
type: number
required:
- op
- hits
- misses
- time
- disk_to_free
- disk_total
title: CacheInfoNotification
type: object
CellChannel:
description: The channel of a cell's output.
enum:
- marimo-error
- media
- output
- pdb
- stderr
- stdin
- stdout
title: CellChannel
CellConfig:
description: 'Internal representation of a cell''s configuration.
This is not part of the public API.'
properties:
column:
anyOf:
- type: integer
- type: 'null'
default: null
disabled:
default: false
type: boolean
expand_output:
default: false
type: boolean
hide_code:
default: false
type: boolean
required: []
title: CellConfig
type: object
CellId:
format: cell-id
type: string
CellNotification:
description: "Updates a cell's state in the frontend.\n\n This is a partial\
\ update: each field carries its own \"unchanged\" semantics,\n documented\
\ per field below. Most fields treat None as \"unchanged\"; fields\n that\
\ need to distinguish \"unchanged\" from \"clear\" use msgspec.UNSET for the\n\
\ former and None for the latter.\n\n Attributes:\n cell_id:\
\ Unique identifier of the cell being updated.\n output: Cell's output.\
\ Use CellOutput.empty() to clear.\n console: Console messages. Single/list\
\ appends, [] clears, None unchanged.\n status: Execution status (idle/running/stale/queued/disabled-transitively).\n\
\ stale_inputs: Whether cell has stale inputs from changed dependencies.\n\
\ run_id: Execution run ID for tracing. Auto-set from context.\n \
\ execution_id: Evaluation of this cell producing the update, when known.\n\
\ serialization: Top-level reusability hint. UNSET unchanged, None\
\ clears, str sets.\n timestamp: Creation timestamp, auto-set."
properties:
cell_id:
$ref: '#/components/schemas/CellId'
console:
anyOf:
- items:
$ref: '#/components/schemas/CellOutput'
type: array
- $ref: '#/components/schemas/CellOutput'
- type: 'null'
default: null
execution_id:
anyOf:
- type: string
- type: 'null'
default: null
op:
enum:
- cell-op
output:
anyOf:
- $ref: '#/components/schemas/CellOutput'
- type: 'null'
default: null
run_id:
anyOf:
- type: string
- type: 'null'
default: null
serialization:
anyOf:
- type: string
- type: 'null'
stale_inputs:
anyOf:
- type: boolean
- type: 'null'
default: null
status:
anyOf:
- enum:
- disabled-transitively
- idle
- queued
- running
- type: 'null'
default: null
timestamp:
type: number
required:
- op
- cell_id
title: CellNotification
type: object
CellOutput:
properties:
channel:
$ref: '#/components/schemas/CellChannel'
code:
type: string
data:
anyOf:
- type: string
- items:
anyOf:
- $ref: '#/components/schemas/SetupRootError'
- $ref: '#/components/schemas/CycleError'
- $ref: '#/components/schemas/MultipleDefinitionError'
- $ref: '#/components/schemas/ImportStarError'
- $ref: '#/components/schemas/LazyImportError'
- $ref: '#/components/schemas/MarimoAncestorStoppedError'
- $ref: '#/components/schemas/MarimoAncestorPreventedError'
- $ref: '#/components/schemas/MarimoExceptionRaisedError'
- $ref: '#/components/schemas/MarimoStrictExecutionError'
- $ref: '#/components/schemas/MarimoInterruptionError'
- $ref: '#/components/schemas/MarimoSyntaxError'
- $ref: '#/components/schemas/MarimoInternalError'
- $ref: '#/components/schemas/MarimoSQLError'
- $ref: '#/components/schemas/UnknownError'
discriminator:
mapping:
ancestor-prevented: '#/components/schemas/MarimoAncestorPreventedError'
ancestor-stopped: '#/components/schemas/MarimoAncestorStoppedError'
cycle: '#/components/schemas/CycleError'
exception: '#/components/schemas/MarimoExceptionRaisedError'
import-star: '#/components/schemas/ImportStarError'
internal: '#/components/schemas/MarimoInternalError'
interruption: '#/components/schemas/MarimoInterruptionError'
lazy-import: '#/components/schemas/LazyImportError'
multiple-defs: '#/components/schemas/MultipleDefinitionError'
setup-refs: '#/components/schemas/SetupRootError'
sql-error: '#/components/schemas/MarimoSQLError'
strict-exception: '#/components/schemas/MarimoStrictExecutionError'
syntax: '#/components/schemas/MarimoSyntaxError'
unknown: '#/components/schemas/UnknownError'
propertyName: type
type: array
- type: object
mimetype:
enum:
- application/json
- application/vnd.jupyter.widget-view+json
- application/vnd.marimo+error
- application/vnd.marimo+mimebundle
- application/vnd.marimo+traceback
- application/vnd.vega.v5+json
- application/vnd.vega.v6+json
- application/vnd.vegalite.v5+json
- application/vnd.vegalite.v6+json
- image/avif
- image/bmp
- image/gif
- image/jpeg
- image/png
- image/svg+xml
- image/tiff
- text/csv
- text/html
- text/latex
- text/markdown
- text/password
- text/plain
- video/mp4
- video/mpeg
timestamp:
type: number
traceback_format:
enum:
- html
- text
required:
- channel
- mimetype
- data
title: CellOutput
type: object
CellOutputs:
description: "Per-cell output snapshot delivered alongside the document snapshot.\n\
\n `output` carries the cell's last main (rich display) output;\n `console_outputs`\
\ carries the buffered stdout/stderr stream from\n its last execution.\
\ Both are keyed by cell id; missing keys mean\n \"no output captured\"\
\ (the cell never ran, or produced nothing on\n that channel)."
properties:
console_outputs:
additionalProperties:
items:
$ref: '#/components/schemas/CellOutput'
type: array
type: object
output:
additionalProperties:
$ref: '#/components/schemas/CellOutput'
type: object
required:
- output
- console_outputs
title: CellOutputs
type: object
ChatAttachment:
properties:
content_type:
anyOf:
- type: string
- type: 'null'
default: null
name:
default: attachment
type: string
url:
type: string
required:
- url
title: ChatAttachment
type: object
ChatMessage:
description: A message in a chat.
properties:
attachments:
anyOf:
- items:
$ref: '#/components/schemas/ChatAttachment'
type: array
- type: 'null'
default: null
content: {}
id:
default: ''
type: string
metadata:
anyOf:
- {}
- type: 'null'
default: null
parts:
default: []
items:
type: object
type: array
role:
enum:
- assistant
- system
- user
required:
- role
- content
title: ChatMessage
type: object
ChatOptions:
description: Used to configure capabilities of the AI agent.
properties:
webSearch:
default: false
type: boolean
required: []
title: ChatOptions
type: object
ChatRequest:
description: 'UIMessages are expected to be AI SDK messages.
See pydantic_ai.ui.vercel_ai.request_types.UIMessage or Vercel AI SDK documentation.'
properties:
id:
anyOf:
- type: string
- type: 'null'
default: null
includeOtherCode:
type: string
model:
anyOf:
- type: string
- type: 'null'
default: null
options:
$ref: '#/components/schemas/ChatOptions'
tools:
anyOf:
- items:
$ref: '#/components/schemas/ToolDefinition'
type: array
- type: 'null'
default: null
uiMessages:
items:
type: object
type: array
variables:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/VariableContext'
type: array
- type: 'null'
default: null
required:
- includeOtherCode
- uiMessages
title: ChatRequest
type: object
ClearCacheRequest:
properties: {}
required: []
title: ClearCacheRequest
type: object
ClientCommand:
anyOf:
- $ref: '#/components/schemas/ExecuteCellsCommand'
- $ref: '#/components/schemas/ExecuteScratchpadCommand'
- $ref: '#/components/schemas/DeleteCellCommand'
- $ref: '#/components/schemas/UpdateCellConfigCommand'
- $ref: '#/components/schemas/UpdateUIElementCommand'
- $ref: '#/components/schemas/ModelCommand'
- $ref: '#/components/schemas/InvokeFunctionCommand'
- $ref: '#/components/schemas/InstallPackagesCommand'
- $ref: '#/components/schemas/PreviewDatasetColumnCommand'
- $ref: '#/components/schemas/PreviewSQLTableCommand'
- $ref: '#/components/schemas/ListSQLTablesCommand'
- $ref: '#/components/schemas/ListSQLSchemasCommand'
- $ref: '#/components/schemas/ValidateSQLCommand'
- $ref: '#/components/schemas/ListDataSourceConnectionCommand'
- $ref: '#/components/schemas/DiscoverDataSourcesCommand'
- $ref: '#/components/schemas/ListSecretKeysCommand'
discriminator:
mapping:
delete-cell: '#/components/schemas/DeleteCellCommand'
discover-data-sources: '#/components/schemas/DiscoverDataSourcesCommand'
execute-cells: '#/components/schemas/ExecuteCellsCommand'
execute-scratchpad: '#/components/schemas/ExecuteScratchpadCommand'
install-packages: '#/components/schemas/InstallPackagesCommand'
invoke-function: '#/components/schemas/InvokeFunctionCommand'
list-data-source-connection: '#/components/schemas/ListDataSourceConnectionCommand'
list-secret-keys: '#/components/schemas/ListSecretKeysCommand'
list-sql-schemas: '#/components/schemas/ListSQLSchemasCommand'
list-sql-tables: '#/components/schemas/ListSQLTablesCommand'
model: '#/components/schemas/ModelCommand'
preview-dataset-column: '#/components/schemas/PreviewDatasetColumnCommand'
preview-sql-table: '#/components/schemas/PreviewSQLTableCommand'
update-cell-config: '#/components/schemas/UpdateCellConfigCommand'
update-ui-element: '#/components/schemas/UpdateUIElementCommand'
validate-sql: '#/components/schemas/ValidateSQLCommand'
propertyName: type
CodeCompletionRequest:
properties:
cellId:
$ref: '#/components/schemas/CellId'
document:
type: string
id:
$ref: '#/components/schemas/RequestId'
required:
- id
- document
- cellId
title: CodeCompletionRequest
type: object
ColumnStats:
description: Represents stats for a column in a data table.
properties:
'false':
anyOf:
- type: integer
- type: 'null'
default: null
max:
anyOf:
- {}
- type: 'null'
default: null
mean:
anyOf:
- {}
- type: 'null'
default: null
median:
anyOf:
- {}
- type: 'null'
default: null
min:
anyOf:
- {}
- type: 'null'
default: null
nulls:
anyOf:
- type: integer
- type: 'null'
default: null
p25:
anyOf:
- {}
- type: 'null'
default: null
p5:
anyOf:
- {}
- type: 'null'
default: null
p75:
anyOf:
- {}
- type: 'null'
default: null
p95:
anyOf:
- {}
- type: 'null'
default: null
std:
anyOf:
- {}
- type: 'null'
default: null
total:
anyOf:
- type: integer
- type: 'null'
default: null
'true':
anyOf:
- type: integer
- type: 'null'
default: null
unique:
anyOf:
- type: integer
- type: 'null'
default: null
required: []
title: ColumnStats
type: object
CompletedRunNotification:
description: The command's reactive cycle ended, after its console was flushed.
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
op:
enum:
- completed-run
outcome:
default: succeeded
enum:
- failed
- interrupted
- succeeded
run_id:
anyOf:
- type: string
- type: 'null'
default: null
required:
- op
title: CompletedRunNotification
type: object
CompletionConfig:
description: "Configuration for code completion.\n\n A dict with key/value\
\ pairs configuring code completion in the marimo\n editor.\n\n **Keys.**\n\
\n - `activate_on_typing`: if `False`, completion won't activate\n until\
\ the completion hotkey is entered\n - `signature_hint_on_typing`: if `False`,\
\ signature hint won't be shown when typing\n - `copilot`: one of `\"github\"\
`, `\"codeium\"`, or `\"custom\"`\n - `codeium_api_key`: the Codeium API\
\ key\n - `auto_close_pairs`: if `False`, typing an opening bracket, parenthesis,\n\
\ or quote will not automatically insert the closing character"
properties:
activate_on_typing:
type: boolean
api_key:
anyOf:
- type: string
- type: 'null'
auto_close_pairs:
type: boolean
base_url:
anyOf:
- type: string
- type: 'null'
codeium_api_key:
anyOf:
- type: string
- type: 'null'
copilot:
anyOf:
- type: boolean
- enum:
- codeium
- custom
- github
model:
anyOf:
- type: string
- type: 'null'
signature_hint_on_typing:
type: boolean
required:
- activate_on_typing
- copilot
- signature_hint_on_typing
title: CompletionConfig
type: object
CompletionOption:
properties:
completion_info:
anyOf:
- type: string
- type: 'null'
name:
type: string
type:
type: string
required:
- name
- type
- completion_info
title: CompletionOption
type: object
CompletionResultNotification:
description: "Code completion result from language server.\n\n Attributes:\n\
\ completion_id: Request ID this responds to.\n prefix_length:\
\ Length of prefix to replace.\n options: Completion options to display."
properties:
completion_id:
$ref: '#/components/schemas/RequestId'
op:
enum:
- completion-result
options:
items:
$ref: '#/components/schemas/CompletionOption'
type: array
prefix_length:
type: integer
required:
- op
- completion_id
- prefix_length
- options
title: CompletionResultNotification
type: object
ConsumerCapabilities:
description: "Per-consumer access capabilities for a session connection.\n\n\
\ - editor: `{edit: True, interact: True}`\n - interactor: `{edit: False,\
\ interact: True}` (default for a secondary\n connection: drives UI state\
\ but cannot edit the notebook)\n - read-only viewer: `{edit: False, interact:\
\ False}` (opt-in, set by a\n deployment's capability provider)\n\n \
\ The server enforces these: control requests are gated against the issuing\n\
\ consumer's stored capabilities at the control-request chokepoint (the\n\
\ authority) and mirrored as an advisory HTTP 403 at the request handlers.\n\
\ Commands classified as `read` in `marimo._session.capabilities` (such\
\ as\n completions and previews) are always permitted."
properties:
edit:
type: boolean
interact:
type: boolean
required:
- edit
- interact
title: ConsumerCapabilities
type: object
ConsumerCapabilitiesNotification:
description: Notification of the frontend consumer's capabilities.
properties:
consumer_capabilities:
$ref: '#/components/schemas/ConsumerCapabilities'
op:
enum:
- consumer-capabilities
required:
- op
- consumer_capabilities
title: ConsumerCapabilitiesNotification
type: object
CopyNotebookRequest:
properties:
destination:
type: string
source:
type: string
required:
- source
- destination
title: CopyNotebookRequest
type: object
CreateCell:
description: Insert a new cell into the notebook.
properties:
after:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
default: null
before:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
default: null
cellId:
$ref: '#/components/schemas/CellId'
code:
type: string
config:
$ref: '#/components/schemas/CellConfig'
name:
type: string
type:
enum:
- create-cell
required:
- type
- cellId
- code
- name
- config
title: CreateCell
type: object
CreateSecretRequest:
properties:
key:
type: string
name:
type: string
provider:
enum:
- dotenv
- env
value:
type: string
required:
- key
- value
- provider
- name
title: CreateSecretRequest
type: object
CycleError:
properties:
edges_with_vars:
items:
items: false
maxItems: 3
minItems: 3
prefixItems:
- type: string
- items:
type: string
type: array
- type: string
type: array
type: array
type:
enum:
- cycle
required:
- type
- edges_with_vars
title: CycleError
type: object
DataColumnPreviewNotification:
description: "Data column preview with stats and visualization.\n\n Inherits\
\ all ColumnPreview attributes.\n\n Attributes:\n table_name: Table\
\ containing the column.\n column_name: Column being previewed."
properties:
chart_code:
anyOf:
- type: string
- type: 'null'
default: null
chart_spec:
anyOf:
- type: string
- type: 'null'
default: null
column_name:
type: string
error:
anyOf:
- type: string
- type: 'null'
default: null
missing_packages:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
op:
enum:
- data-column-preview
stats:
anyOf:
- $ref: '#/components/schemas/ColumnStats'
- type: 'null'
default: null
table_name:
type: string
required:
- op
- table_name
- column_name
title: DataColumnPreviewNotification
type: object
DataSourceConnection:
description: "Represents a data source connection.\n\nAttributes:\n source\
\ (str): The source of the data source connection. E.g 'postgres'.\n dialect\
\ (str): The dialect of the data source connection. E.g 'postgresql'.\n \
\ name (str): The name of the data source connection. E.g 'engine'.\n \
\ display_name (str): The display name of the data source connection. E.g\
\ 'PostgresQL (engine)'.\n databases (List[Database]): The databases in\
\ the data source connection.\n default_database (Optional[str]): The default\
\ database in the data source connection.\n default_schema (Optional[str]):\
\ The default schema in the data source connection."
properties:
databases:
items:
$ref: '#/components/schemas/Database'
type: array
default_database:
anyOf:
- type: string
- type: 'null'
default: null
default_schema:
anyOf:
- type: string
- type: 'null'
default: null
dialect:
type: string
display_name:
type: string
name:
type: string
source:
type: string
required:
- source
- dialect
- name
- display_name
- databases
title: DataSourceConnection
type: object
DataSourceConnectionsNotification:
description: "Available data source connections for SQL cells.\n\n Attributes:\n\
\ connections: Available data source connections."
properties:
connections:
items:
$ref: '#/components/schemas/DataSourceConnection'
type: array
op:
enum:
- data-source-connections
required:
- op
- connections
title: DataSourceConnectionsNotification
type: object
DataSourceDiscoveryResultNotification:
description: "High-confidence datasource connections discovered by the kernel.\n\
\n Attributes:\n request_id: Request ID this responds to.\n \
\ sources: Detected datasource connection configurations."
properties:
op:
enum:
- data-source-discovery-result
request_id:
$ref: '#/components/schemas/RequestId'
sources:
items:
$ref: '#/components/schemas/DetectedDataSource'
type: array
required:
- op
- request_id
- sources
title: DataSourceDiscoveryResultNotification
type: object
DataTable:
description: "Represents a data table.\n\nAttributes:\n source_type (DataTableSource):\
\ Type of data source ('local', 'duckdb', 'connection').\n source (str):\
\ Can be dialect, or source db name.\n name (str): Name of the data table.\n\
\ num_rows (Optional[int]): Total number of rows in the table, if known.\n\
\ num_columns (Optional[int]): Total number of columns in the table, if\
\ known.\n variable_name (Optional[VariableName]): Variable name referencing\
\ this table in code.\n columns (List[DataTableColumn]): List of column\
\ definitions and metadata.\n engine (Optional[VariableName]): Database\
\ engine or connection handler, if any.\n type (DataTableType): Table type,\
\ either 'table' or 'view'. Defaults to 'table'.\n primary_keys (Optional[List[str]]):\
\ Column names used as primary keys, if any.\n indexes (Optional[List[str]]):\
\ Column names used as indexes, if any."
properties:
columns:
items:
$ref: '#/components/schemas/DataTableColumn'
type: array
engine:
anyOf:
- $ref: '#/components/schemas/VariableName'
- type: 'null'
default: null
indexes:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
name:
type: string
num_columns:
anyOf:
- type: integer
- type: 'null'
num_rows:
anyOf:
- type: integer
- type: 'null'
primary_keys:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
source:
type: string
source_type:
enum:
- catalog
- connection
- duckdb
- local
type:
default: table
enum:
- table
- view
variable_name:
anyOf:
- $ref: '#/components/schemas/VariableName'
- type: 'null'
required:
- source_type
- source
- name
- num_rows
- num_columns
- variable_name
- columns
title: DataTable
type: object
DataTableColumn:
description: "Represents a column in a data table.\n\nAttributes:\n name\
\ (str): The name of the column.\n type (DataType): The data type of the\
\ column.\n external_type (ExternalDataType): The raw data type of the\
\ column.\n sample_values (List[Any]): The sample values of the column."
properties:
external_type:
type: string
name:
type: string
sample_values:
type: array
type:
enum:
- boolean
- date
- datetime
- geometry
- integer
- number
- string
- time
- unknown
required:
- name
- type
- external_type
- sample_values
title: DataTableColumn
type: object
DataType:
enum:
- boolean
- date
- datetime
- geometry
- integer
- number
- string
- time
- unknown
Database:
description: "Represents a collection of schemas.\n\nAttributes:\n name (str):\
\ The name of the database\n dialect (str): The dialect of the database\n\
\ schemas (List[Schema]): List of schemas in the database.\n schemas_resolved\
\ (bool): True when `schemas` has been enumerated.\n False when schema\
\ discovery was deferred. Defaults to True\n engine (Optional[VariableName]):\
\ Database engine or connection handler, if any."
properties:
dialect:
type: string
engine:
anyOf:
- $ref: '#/components/schemas/VariableName'
- type: 'null'
default: null
name:
type: string
schemas:
items:
$ref: '#/components/schemas/Schema'
type: array
schemas_resolved:
default: true
type: boolean
required:
- name
- dialect
- schemas
title: Database
type: object
DatasetsNotification:
description: "Available datasets for data explorer.\n\n Attributes:\n \
\ tables: Available data tables/datasets.\n clear_channel: If set,\
\ clears tables from this channel first."
properties:
clear_channel:
anyOf:
- enum:
- catalog
- connection
- duckdb
- local
- type: 'null'
default: null
op:
enum:
- datasets
tables:
items:
$ref: '#/components/schemas/DataTable'
type: array
required:
- op
- tables
title: DatasetsNotification
type: object
DatasourcesConfig:
description: "Configuration for datasources panel.\n\n **Keys.**\n\n -\
\ `auto_discover_schemas`: if `True`, include schemas in the datasource\n\
\ - `auto_discover_tables`: if `True`, include tables in the datasource\n\
\ - `auto_discover_columns`: if `True`, include columns & table metadata\
\ in the datasource"
properties:
auto_discover_columns:
anyOf:
- type: boolean
- enum:
- auto
auto_discover_schemas:
anyOf:
- type: boolean
- enum:
- auto
auto_discover_tables:
anyOf:
- type: boolean
- enum:
- auto
required: []
title: DatasourcesConfig
type: object
DebugCellRequest:
properties:
cellId:
$ref: '#/components/schemas/CellId'
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
required:
- cellId
title: DebugCellRequest
type: object
DeleteCell:
description: Remove a cell from the notebook.
properties:
cellId:
$ref: '#/components/schemas/CellId'
type:
enum:
- delete-cell
required:
- type
- cellId
title: DeleteCell
type: object
DeleteCellCommand:
description: "Delete a cell from the notebook.\n\n Removes cell from the\
\ dependency graph and cleans up its variables.\n Dependent cells may become\
\ stale.\n\n Attributes:\n cell_id: Cell to delete."
properties:
cellId:
$ref: '#/components/schemas/CellId'
type:
enum:
- delete-cell
required:
- type
- cellId
title: DeleteCellCommand
type: object
DeleteSecretRequest:
properties:
key:
type: string
required:
- key
title: DeleteSecretRequest
type: object
DependencyTag:
properties:
kind:
type: string
value:
type: string
required:
- kind
- value
title: DependencyTag
type: object
DependencyTreeNode:
properties:
dependencies:
items:
$ref: '#/components/schemas/DependencyTreeNode'
type: array
name:
type: string
tags:
items:
$ref: '#/components/schemas/DependencyTag'
type: array
version:
anyOf:
- type: string
- type: 'null'
required:
- name
- version
- tags
- dependencies
title: DependencyTreeNode
type: object
DependencyTreeResponse:
properties:
context:
anyOf:
- $ref: '#/components/schemas/SandboxPackageContext'
- $ref: '#/components/schemas/PackageManagerContext'
discriminator:
mapping:
package-manager: '#/components/schemas/PackageManagerContext'
sandbox: '#/components/schemas/SandboxPackageContext'
propertyName: kind
tree:
anyOf:
- $ref: '#/components/schemas/DependencyTreeNode'
- type: 'null'
required:
- tree
- context
title: DependencyTreeResponse
type: object
DetectedDataSource:
description: A secret-free datasource suggestion produced by the kernel.
properties:
category:
enum:
- catalog
- database
- object-storage
code:
type: string
confidence:
enum:
- high
- medium
configuration:
items:
$ref: '#/components/schemas/DetectedDataSourceConfiguration'
type: array
displayName:
type: string
hidesWhen:
anyOf:
- $ref: '#/components/schemas/DialectHidesWhen'
- $ref: '#/components/schemas/StorageHidesWhen'
discriminator:
mapping:
dialect: '#/components/schemas/DialectHidesWhen'
storage: '#/components/schemas/StorageHidesWhen'
propertyName: kind
id:
type: string
integration:
type: string
origins:
items:
$ref: '#/components/schemas/DetectedDataSourceOrigin'
type: array
required:
- id
- integration
- category
- displayName
- confidence
- origins
- configuration
- code
- hidesWhen
title: DetectedDataSource
type: object
DetectedDataSourceConfiguration:
properties:
field:
type: string
value:
anyOf:
- $ref: '#/components/schemas/EnvironmentVariableDiscoveryValue'
- $ref: '#/components/schemas/SafeLiteralDiscoveryValue'
discriminator:
mapping:
environment-variable: '#/components/schemas/EnvironmentVariableDiscoveryValue'
safe-literal: '#/components/schemas/SafeLiteralDiscoveryValue'
propertyName: kind
required:
- field
- value
title: DetectedDataSourceConfiguration
type: object
DetectedDataSourceOrigin:
properties:
label:
type: string
type:
enum:
- configuration
- environment
required:
- type
- label
title: DetectedDataSourceOrigin
type: object
DiagnosticsConfig:
description: "Configuration options for diagnostics.\n\n **Keys.**\n\n \
\ - `enabled`: if `True`, diagnostics will be shown in the editor\n -\
\ `sql_linter`: if `True`, SQL cells will have linting enabled"
properties:
enabled:
type: boolean
sql_linter:
type: boolean
required: []
title: DiagnosticsConfig
type: object
DialectHidesWhen:
description: Hide this suggestion when a live SQL engine dialect contains a
substring.
properties:
kind:
enum:
- dialect
substrings:
items:
type: string
type: array
required:
- kind
- substrings
title: DialectHidesWhen
type: object
DiscoverDataSourcesCommand:
description: "Discover datasource connections from the live kernel environment\
\ and configuration.\n\n Attributes:\n request_id: Unique identifier\
\ for this request."
properties:
requestId:
$ref: '#/components/schemas/RequestId'
type:
enum:
- discover-data-sources
required:
- type
- requestId
title: DiscoverDataSourcesCommand
type: object
DiscoverDataSourcesRequest:
properties:
requestId:
$ref: '#/components/schemas/RequestId'
required:
- requestId
title: DiscoverDataSourcesRequest
type: object
DisplayConfig:
description: "Configuration for display.\n\n **Keys.**\n\n - `theme`:\
\ `\"light\"`, `\"dark\"`, or `\"system\"`\n - `code_editor_font_size`:\
\ font size for the code editor\n - `cell_output`: `\"above\"` or `\"below\"\
`\n - `dataframes`: `\"rich\"` or `\"plain\"`\n - `custom_css`: list\
\ of paths to custom CSS files\n - `default_table_page_size`: default number\
\ of rows to display in tables\n - `default_table_max_columns`: default\
\ maximum number of columns to display in tables\n - `reference_highlighting`:\
\ if `True`, highlight reactive variable references\n - `code_lens`: if\
\ `True`, show inline icons in cell editors linking\n datasources, storage\
\ buckets, and caches to their panels\n - `locale`: locale for date formatting\
\ and internationalization (e.g., \"en-US\", \"en-GB\", \"de-DE\")"
properties:
cell_output:
enum:
- above
- below
code_editor_font_size:
type: integer
code_lens:
type: boolean
custom_css:
items:
type: string
type: array
dataframes:
enum:
- plain
- rich
default_table_max_columns:
type: integer
default_table_page_size:
type: integer
default_width:
enum:
- columns
- compact
- full
- medium
- normal
locale:
anyOf:
- type: string
- type: 'null'
reference_highlighting:
type: boolean
theme:
enum:
- dark
- light
- system
required:
- cell_output
- code_editor_font_size
- dataframes
- default_table_max_columns
- default_table_page_size
- default_width
- theme
title: DisplayConfig
type: object
EnvironmentOperation:
description: Current progress and logs for one execution of environment work.
properties:
action:
enum:
- install
- prepare
- remove
- sync
logs:
additionalProperties:
type: string
type: object
operation_id:
type: string
packages:
additionalProperties:
enum:
- failed
- queued
- restart-required
- running
- succeeded
type: object
source:
enum:
- kernel
- server
status:
anyOf:
- $ref: '#/components/schemas/OperationRunning'
- $ref: '#/components/schemas/OperationSucceeded'
- $ref: '#/components/schemas/OperationRestartRequired'
- $ref: '#/components/schemas/OperationFailed'
- $ref: '#/components/schemas/OperationCancelled'
discriminator:
mapping:
cancelled: '#/components/schemas/OperationCancelled'
failed: '#/components/schemas/OperationFailed'
restart-required: '#/components/schemas/OperationRestartRequired'
running: '#/components/schemas/OperationRunning'
succeeded: '#/components/schemas/OperationSucceeded'
propertyName: kind
required:
- operation_id
- action
- status
- packages
- logs
- source
title: EnvironmentOperation
type: object
EnvironmentOperationNotification:
description: "Current operation progress and changes to its named log streams.\n\
\n Package statuses replace the previous map. Log chunks append to a stream,\n\
\ or replace it when `log_mode` is `replace`. The operation status determines\n\
\ completion independently of its packages and output streams."
properties:
action:
enum:
- install
- prepare
- remove
- sync
log_mode:
enum:
- append
- replace
logs:
additionalProperties:
type: string
type: object
op:
enum:
- environment-operation
operation_id:
type: string
packages:
additionalProperties:
enum:
- failed
- queued
- restart-required
- running
- succeeded
type: object
source:
enum:
- kernel
- server
status:
anyOf:
- $ref: '#/components/schemas/OperationRunning'
- $ref: '#/components/schemas/OperationSucceeded'
- $ref: '#/components/schemas/OperationRestartRequired'
- $ref: '#/components/schemas/OperationFailed'
- $ref: '#/components/schemas/OperationCancelled'
discriminator:
mapping:
cancelled: '#/components/schemas/OperationCancelled'
failed: '#/components/schemas/OperationFailed'
restart-required: '#/components/schemas/OperationRestartRequired'
running: '#/components/schemas/OperationRunning'
succeeded: '#/components/schemas/OperationSucceeded'
propertyName: kind
required:
- op
- operation_id
- action
- status
- source
- packages
- logs
- log_mode
title: EnvironmentOperationNotification
type: object
EnvironmentState:
description: Preparation, active operations, the latest mutation, and restarts.
properties:
operations:
items:
$ref: '#/components/schemas/EnvironmentOperation'
type: array
restart_required:
type: boolean
required:
- restart_required
- operations
title: EnvironmentState
type: object
EnvironmentStateNotification:
description: Replace the current state for one environment on connection.
properties:
op:
enum:
- environment-state
source:
enum:
- kernel
- server
state:
$ref: '#/components/schemas/EnvironmentState'
required:
- op
- source
- state
title: EnvironmentStateNotification
type: object
EnvironmentVariableDiscoveryValue:
description: A reference to an environment variable, never its value.
properties:
kind:
enum:
- environment-variable
name:
type: string
required:
- kind
- name
title: EnvironmentVariableDiscoveryValue
type: object
EsmSpec:
description: "Where the frontend imports a widget's ESM from, and which version.\n\
\n Specs travel only on kernel-authored notifications, never in model\n\
\ state: state is client-writable and echoed to peers, so executing\n \
\ code from it would let one client run code on another.\n\n Attributes:\n\
\ url: URL to import the ESM from. A virtual file for inline\n \
\ source; an external URL when `_esm` is itself a URL.\n hash:\
\ Hash of the `_esm` string. Keys the frontend module cache\n and\
\ signals code changes (hot reload)."
properties:
hash:
type: string
url:
type: string
required:
- url
- hash
title: EsmSpec
type: object
ExecuteCellsCommand:
description: "Execute multiple cells in a batch.\n\n Executes multiple cells\
\ with their corresponding code. The kernel manages\n dependency tracking\
\ and reactive execution.\n\n Attributes:\n cell_ids: Cells to execute.\n\
\ codes: Python code for each cell. Must match length of cell_ids.\n\
\ request: HTTP request context if available.\n timestamp: Unix\
\ timestamp when command was created.\n run_id: Optional correlation\
\ ID. When set, the run's notifications\n and its `CompletedRunNotification`\
\ carry it.\n allow_stdin: Whether cells may request interactive input."
properties:
allowStdin:
default: true
type: boolean
cellIds:
items:
$ref: '#/components/schemas/CellId'
type: array
codes:
items:
type: string
type: array
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
runId:
anyOf:
- type: string
- type: 'null'
default: null
timestamp:
type: number
type:
enum:
- execute-cells
required:
- type
- cellIds
- codes
title: ExecuteCellsCommand
type: object
ExecuteCellsRequest:
properties:
cellIds:
items:
$ref: '#/components/schemas/CellId'
type: array
codes:
items:
type: string
type: array
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
required:
- cellIds
- codes
title: ExecuteCellsRequest
type: object
ExecuteScratchpadCommand:
description: "Execute code in the scratchpad.\n\n The scratchpad is a temporary\
\ execution environment that doesn't affect\n the notebook's cells or dependencies.\
\ Runs in an isolated cell with a copy\n of the global namespace, useful\
\ for experimentation.\n\n Attributes:\n code: Python code to execute.\n\
\ request: HTTP request context if available.\n notebook_cells:\
\ Snapshot of notebook cells from the session document.\n Used\
\ to populate the document ContextVar so code_mode can read\n cell\
\ ordering, code, names, and configs.\n cell_outputs: Snapshot of per-cell\
\ outputs (main + console) from the\n session view. Populates a\
\ parallel ContextVar so code_mode can\n expose `cell.output` and\
\ `cell.console_outputs`. Frozen at\n scratchpad start \u2014 not\
\ refreshed when `ctx.run_cell` produces\n new outputs in the same\
\ batch.\n run_id: Optional correlation ID. When set, the\n \
\ `CompletedRunNotification` emitted at the end of this command\n \
\ carries the same `run_id` so a caller holding a\n `ScratchCellListener`\
\ can filter for *its* completion and\n ignore `CompletedRun` events\
\ from unrelated commands on the\n same session.\n allow_stdin:\
\ Whether code may request interactive input. When false,\n input\
\ reads receive EOF for the duration of this command."
properties:
allowStdin:
default: true
type: boolean
cellOutputs:
anyOf:
- $ref: '#/components/schemas/CellOutputs'
- type: 'null'
default: null
code:
type: string
notebookCells:
anyOf:
- items:
$ref: '#/components/schemas/NotebookCell'
type: array
- type: 'null'
default: null
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
runId:
anyOf:
- type: string
- type: 'null'
default: null
type:
enum:
- execute-scratchpad
required:
- type
- code
title: ExecuteScratchpadCommand
type: object
ExecuteScratchpadRequest:
properties:
allowStdin:
default: true
type: boolean
cellOutputs:
anyOf:
- $ref: '#/components/schemas/CellOutputs'
- type: 'null'
default: null
code:
type: string
notebookCells:
anyOf:
- items:
$ref: '#/components/schemas/NotebookCell'
type: array
- type: 'null'
default: null
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
runId:
anyOf:
- type: string
- type: 'null'
default: null
required:
- code
title: ExecuteScratchpadRequest
type: object
ExecutionNotification:
description: "An attempt's lifecycle, independent of a cell's displayed status.\n\
\n `planned` supplies the source and identity before output is reported.\n\
\ `running` means evaluation began. `completed` follows the final output\n\
\ and errors, including for attempts that never ran. Buffered and background\n\
\ console output may still arrive with the completed attempt's identity."
properties:
caused_by:
anyOf:
- type: string
- type: 'null'
default: null
cell_id:
$ref: '#/components/schemas/CellId'
code:
anyOf:
- type: string
- type: 'null'
default: null
depends_on:
anyOf:
- additionalProperties:
anyOf:
- $ref: '#/components/schemas/Revision'
- type: 'null'
type: object
- type: 'null'
default: null
execution_id:
type: string
op:
enum:
- execution
phase:
enum:
- completed
- planned
- running
run_id:
anyOf:
- type: string
- type: 'null'
required:
- op
- execution_id
- cell_id
- run_id
- phase
title: ExecutionNotification
type: object
ExportAsHTMLRequest:
description: "Request a static HTML export.\n\n `layout` carries the current\
\ client layout. An omitted field reads the\n saved layout file, `null`\
\ selects the vertical layout, and an object uses\n that serialized layout\
\ for this export."
properties:
assetUrl:
anyOf:
- type: string
- type: 'null'
default: null
download:
type: boolean
files:
items:
type: string
type: array
includeCode:
type: boolean
layout:
anyOf:
- $ref: '#/components/schemas/LayoutConfig'
- type: 'null'
required:
- download
- files
- includeCode
title: ExportAsHTMLRequest
type: object
ExportAsIPYNBRequest:
properties:
download:
type: boolean
includeOutputs:
default: true
type: boolean
sortMode:
default: top-down
enum:
- top-down
- topological
required:
- download
title: ExportAsIPYNBRequest
type: object
ExportAsMarkdownRequest:
properties:
download:
type: boolean
flavor:
anyOf:
- enum:
- mdx
- mystmd
- pymdown
- qmd
- type: 'null'
default: null
required:
- download
title: ExportAsMarkdownRequest
type: object
ExportAsPDFRequest:
properties:
includeInputs:
default: false
type: boolean
includeOutputs:
default: true
type: boolean
preset:
default: document
enum:
- document
- slides
webpdf:
type: boolean
required:
- webpdf
title: ExportAsPDFRequest
type: object
ExportAsScriptRequest:
properties:
download:
type: boolean
required:
- download
title: ExportAsScriptRequest
type: object
ExportAvailabilityResponse:
properties:
formats:
items:
$ref: '#/components/schemas/ExportFormatAvailability'
type: array
source:
enum:
- server
required:
- source
- formats
title: ExportAvailabilityResponse
type: object
ExportFormatAvailability:
properties:
dependenciesAvailable:
type: boolean
format:
enum:
- html
- ipynb
- markdown
- pdf
- script
missingPackages:
items:
type: string
type: array
missingSetup:
items:
$ref: '#/components/schemas/ExportSetupRequirement'
type: array
required:
- format
- dependenciesAvailable
- missingPackages
- missingSetup
title: ExportFormatAvailability
type: object
ExportSetupRequirement:
properties:
command:
type: string
name:
enum:
- playwright-chromium
required:
- name
- command
title: ExportSetupRequirement
type: object
FileBrowserConfig:
description: "Configuration for the file browser panel.\n\n **Keys.**\n\n\
\ - `folders`: additional absolute folders to show in the file browser"
properties:
folders:
items:
$ref: '#/components/schemas/FolderConfig'
type: array
required: []
title: FileBrowserConfig
type: object
FileCopyRequest:
properties:
newPath:
type: string
path:
type: string
required:
- path
- newPath
title: FileCopyRequest
type: object
FileCopyResponse:
properties:
info:
anyOf:
- $ref: '#/components/schemas/FileInfo'
- type: 'null'
default: null
message:
anyOf:
- type: string
- type: 'null'
default: null
success:
type: boolean
required:
- success
title: FileCopyResponse
type: object
FileCreateMultipartRequest:
description: "multipart/form-data body for POST /api/files/create.\n\n Schema-only:\
\ this struct exists to describe the multipart shape in\n OpenAPI. At runtime,\
\ the endpoint reads the string fields from\n `MultipartRequest.body` and\
\ the uploaded bytes from\n `MultipartRequest.files[\"file\"]` \u2014 `body.file`\
\ is never populated."
properties:
file:
anyOf:
- type: string
- type: 'null'
default: null
format: binary
name:
type: string
path:
type: string
type:
enum:
- directory
- file
- notebook
required:
- path
- type
- name
title: FileCreateMultipartRequest
type: object
FileCreateRequest:
properties:
contents:
anyOf:
- type: string
- type: 'null'
default: null
name:
type: string
path:
type: string
type:
enum:
- directory
- file
- notebook
required:
- path
- type
- name
title: FileCreateRequest
type: object
FileCreateResponse:
properties:
info:
anyOf:
- $ref: '#/components/schemas/FileInfo'
- type: 'null'
default: null
message:
anyOf:
- type: string
- type: 'null'
default: null
success:
type: boolean
required:
- success
title: FileCreateResponse
type: object
FileDeleteRequest:
properties:
path:
type: string
required:
- path
title: FileDeleteRequest
type: object
FileDeleteResponse:
properties:
message:
anyOf:
- type: string
- type: 'null'
default: null
success:
type: boolean
required:
- success
title: FileDeleteResponse
type: object
FileDetailsRequest:
properties:
maxBytes:
anyOf:
- type: integer
- type: 'null'
default: null
path:
type: string
required:
- path
title: FileDetailsRequest
type: object
FileDetailsResponse:
properties:
contents:
anyOf:
- type: string
- type: 'null'
default: null
file:
$ref: '#/components/schemas/FileInfo'
isBase64:
default: false
type: boolean
isTooLarge:
default: false
type: boolean
mimeType:
anyOf:
- type: string
- type: 'null'
default: null
required:
- file
title: FileDetailsResponse
type: object
FileInfo:
properties:
children:
default: []
items:
$ref: '#/components/schemas/FileInfo'
type: array
id:
type: string
isDirectory:
type: boolean
isMarimoFile:
type: boolean
lastModified:
anyOf:
- type: number
- type: 'null'
default: null
name:
type: string
opengraph:
anyOf:
- $ref: '#/components/schemas/OpenGraphMetadata'
- type: 'null'
default: null
path:
type: string
size:
anyOf:
- type: integer
- type: 'null'
default: null
required:
- id
- path
- name
- isDirectory
- isMarimoFile
title: FileInfo
type: object
FileListRequest:
properties:
path:
anyOf:
- type: string
- type: 'null'
default: null
required: []
title: FileListRequest
type: object
FileListResponse:
properties:
files:
items:
$ref: '#/components/schemas/FileInfo'
type: array
root:
type: string
required:
- files
- root
title: FileListResponse
type: object
FileMoveRequest:
properties:
newPath:
type: string
path:
type: string
required:
- path
- newPath
title: FileMoveRequest
type: object
FileMoveResponse:
properties:
info:
anyOf:
- $ref: '#/components/schemas/FileInfo'
- type: 'null'
default: null
message:
anyOf:
- type: string
- type: 'null'
default: null
success:
type: boolean
required:
- success
title: FileMoveResponse
type: object
FileOpenRequest:
properties:
lineNumber:
anyOf:
- type: integer
- type: 'null'
default: null
path:
type: string
required:
- path
title: FileOpenRequest
type: object
FileRoot:
properties:
isPrimary:
type: boolean
name:
type: string
path:
type: string
required:
- path
- name
- isPrimary
title: FileRoot
type: object
FileRootsResponse:
properties:
roots:
items:
$ref: '#/components/schemas/FileRoot'
type: array
required:
- roots
title: FileRootsResponse
type: object
FileSearchRequest:
properties:
depth:
default: 3
type: integer
includeDirectories:
default: true
type: boolean
includeFiles:
default: true
type: boolean
includeHidden:
default: true
type: boolean
limit:
default: 100
type: integer
path:
anyOf:
- type: string
- type: 'null'
default: null
query:
type: string
required:
- query
title: FileSearchRequest
type: object
FileSearchResponse:
properties:
files:
items:
$ref: '#/components/schemas/FileInfo'
type: array
query:
type: string
totalFound:
type: integer
required:
- files
- query
- totalFound
title: FileSearchResponse
type: object
FileUpdateRequest:
properties:
contents:
type: string
path:
type: string
required:
- path
- contents
title: FileUpdateRequest
type: object
FileUpdateResponse:
properties:
info:
anyOf:
- $ref: '#/components/schemas/FileInfo'
- type: 'null'
default: null
message:
anyOf:
- type: string
- type: 'null'
default: null
success:
type: boolean
required:
- success
title: FileUpdateResponse
type: object
FocusCellNotification:
description: "Focuses a cell (kiosk mode).\n\n Attributes:\n cell_id:\
\ Cell to focus."
properties:
cell_id:
$ref: '#/components/schemas/CellId'
op:
enum:
- focus-cell
required:
- op
- cell_id
title: FocusCellNotification
type: object
FocusCellRequest:
properties:
cellId:
$ref: '#/components/schemas/CellId'
required:
- cellId
title: FocusCellRequest
type: object
FolderConfig:
description: "Configuration for an additional file browser root.\n\n **Keys.**\n\
\n - `path`: the absolute path to the folder\n - `name`: an optional\
\ display name for the folder"
properties:
name:
type: string
path:
type: string
required:
- path
title: FolderConfig
type: object
FormatCellsRequest:
properties:
codes:
additionalProperties:
type: string
type: object
lineLength:
type: integer
required:
- codes
- lineLength
title: FormatCellsRequest
type: object
FormatResponse:
properties:
codes:
additionalProperties:
type: string
type: object
required:
- codes
title: FormatResponse
type: object
FormattingConfig:
description: "Configuration for code formatting.\n\n **Keys.**\n\n - `line_length`:\
\ max line length"
properties:
infer_types:
enum:
- jedi
- 'off'
line_length:
type: integer
required:
- line_length
title: FormattingConfig
type: object
FunctionCallResultNotification:
description: "Result of a frontend-initiated function call.\n\n Attributes:\n\
\ function_call_id: ID matching the original request.\n return_value:\
\ Function return value as JSON.\n status: Human-readable success/failure\
\ status.\n found: Whether the requested function was located in the\
\ registry.\n False signals a transient registry desync, so the\
\ request is safe\n to retry. True means no retry will help: a\
\ non-ok status then\n reflects a failure unrelated to lookup,\
\ such as the function\n raising during execution or not being\
\ associated with a cell."
properties:
found:
type: boolean
function_call_id:
$ref: '#/components/schemas/RequestId'
op:
enum:
- function-call-result
return_value: {}
status:
$ref: '#/components/schemas/HumanReadableStatus'
required:
- op
- function_call_id
- return_value
- status
- found
title: FunctionCallResultNotification
type: object
GetCacheInfoRequest:
properties: {}
required: []
title: GetCacheInfoRequest
type: object
GitHubConfig:
description: "Configuration options for GitHub Copilot.\n\n **Keys.**\n\n\
\ - `api_key`: a GitHub Copilot token or an `env:` reference\n - `base_url`:\
\ the base URL for the GitHub Copilot API\n - `copilot_settings`: configuration\
\ settings for GitHub Copilot LSP.\n Supports settings like `http`\
\ (proxy configuration), `telemetry`,\n and `github-enterprise` (enterprise\
\ URI)."
properties:
api_key:
type: string
base_url:
type: string
copilot_settings:
type: object
required: []
title: GitHubConfig
type: object
GoogleAiConfig:
description: "Configuration options for Google AI.\n\n **Keys.**\n\n -\
\ `api_key`: the Google AI API key or an `env:` reference"
properties:
api_key:
type: string
required: []
title: GoogleAiConfig
type: object
HTTPRequest:
description: "Serializable HTTP request representation.\n\n Mimics Starlette/FastAPI\
\ Request but is pickle-able and contains only a safe\n subset of data.\
\ Excludes session and auth to prevent exposing sensitive data.\n\n Attributes:\n\
\ url: Serialized URL with path, port, scheme, netloc, query, hostname.\n\
\ base_url: Serialized base URL.\n headers: Request headers\
\ (marimo-specific headers excluded).\n query_params: Query parameters\
\ mapped to lists of values.\n path_params: Path parameters from the\
\ URL route.\n cookies: Request cookies.\n meta: User-defined\
\ storage for custom data.\n user: User info from authentication middleware\
\ (e.g., is_authenticated, username)."
properties:
base_url:
type: object
cookies:
additionalProperties:
type: string
type: object
headers:
additionalProperties:
type: string
type: object
meta:
type: object
path_params:
type: object
query_params:
additionalProperties:
items:
type: string
type: array
type: object
url:
type: object
user: {}
required:
- url
- base_url
- headers
- query_params
- path_params
- cookies
- meta
- user
title: HTTPRequest
type: object
HumanReadableStatus:
description: "Human-readable status for operation results.\n\n Attributes:\n\
\ code: Status code (\"ok\" or \"error\").\n title: Optional\
\ short title.\n message: Optional detailed description."
properties:
code:
enum:
- error
- ok
message:
anyOf:
- type: string
- type: 'null'
default: null
title:
anyOf:
- type: string
- type: 'null'
default: null
required:
- code
title: HumanReadableStatus
type: object
ImportStarError:
properties:
lineno:
anyOf:
- type: integer
- type: 'null'
default: null
msg:
type: string
type:
enum:
- import-star
required:
- type
- msg
title: ImportStarError
type: object
InstallExportRequirementsRequest:
properties:
format:
enum:
- html
- ipynb
- markdown
- pdf
- script
required:
- format
title: InstallExportRequirementsRequest
type: object
InstallPackagesCommand:
description: "Install Python packages.\n\n Installs missing packages using\
\ the specified package manager. Triggered\n automatically on import errors\
\ or manually by the user.\n\n Attributes:\n manager: Package manager\
\ to use ('pip', 'conda', 'uv', etc.).\n versions: Package names mapped\
\ to version specifiers. Empty version\n means install latest.\n\
\ index_urls: Alternative package index URLs. Primary index first,\n\
\ then extras. Honored by backends that support custom\n\
\ indexes (currently micropip); other backends ignore it.\n\
\ source: Where to install. \"kernel\" (default) dispatches to the\
\ kernel\n subprocess; \"server\" installs directly into the\
\ server's Python\n environment (sys.executable), used when\
\ the server itself needs\n a package (e.g. nbformat for IPYNB\
\ auto-export in sandbox mode)."
properties:
indexUrls:
default: []
items:
type: string
type: array
manager:
type: string
source:
default: kernel
enum:
- kernel
- server
type:
enum:
- install-packages
versions:
additionalProperties:
type: string
type: object
required:
- type
- manager
- versions
title: InstallPackagesCommand
type: object
InstallPackagesRequest:
properties:
indexUrls:
default: []
items:
type: string
type: array
manager:
type: string
source:
default: kernel
enum:
- kernel
- server
versions:
additionalProperties:
type: string
type: object
required:
- manager
- versions
title: InstallPackagesRequest
type: object
InstantiateNotebookRequest:
properties:
autoRun:
default: true
type: boolean
codes:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
default: null
objectIds:
items:
$ref: '#/components/schemas/UIElementId'
type: array
values:
type: array
required:
- objectIds
- values
title: InstantiateNotebookRequest
type: object
InterruptedNotification:
description: Kernel was interrupted by user (SIGINT/Ctrl+C).
properties:
op:
enum:
- interrupted
run_id:
anyOf:
- type: string
- type: 'null'
required:
- op
title: InterruptedNotification
type: object
InvokeAiToolRequest:
properties:
arguments:
type: object
toolName:
type: string
required:
- toolName
- arguments
title: InvokeAiToolRequest
type: object
InvokeAiToolResponse:
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
result: {}
success:
type: boolean
toolName:
type: string
required:
- success
- toolName
- result
title: InvokeAiToolResponse
type: object
InvokeFunctionCommand:
description: "Invoke a function from a UI element.\n\n Called when a UI element\
\ needs to invoke a Python function.\n\n Attributes:\n function_call_id:\
\ Unique identifier for this call.\n namespace: Namespace where the\
\ function is registered.\n function_name: Function to invoke.\n \
\ args: Keyword arguments for the function."
properties:
args:
type: object
functionCallId:
$ref: '#/components/schemas/RequestId'
functionName:
type: string
namespace:
type: string
type:
enum:
- invoke-function
required:
- type
- functionCallId
- namespace
- functionName
- args
title: InvokeFunctionCommand
type: object
InvokeFunctionRequest:
properties:
args:
type: object
functionCallId:
$ref: '#/components/schemas/RequestId'
functionName:
type: string
namespace:
type: string
required:
- functionCallId
- namespace
- functionName
- args
title: InvokeFunctionRequest
type: object
KernelCapabilitiesNotification:
description: "Kernel capabilities detected at startup.\n\n All fields auto-detected\
\ in __post_init__.\n\n Attributes:\n terminal: Terminal access\
\ (unavailable on Windows/Pyodide).\n pylsp: Python Language Server\
\ Protocol installed.\n ty: ty type checker installed.\n basedpyright:\
\ basedpyright type checker installed."
properties:
basedpyright:
default: false
type: boolean
pylsp:
default: false
type: boolean
pyrefly:
default: false
type: boolean
terminal:
default: false
type: boolean
ty:
default: false
type: boolean
required: []
title: KernelCapabilitiesNotification
type: object
KernelReadyNotification:
description: "Kernel ready for execution. First notification sent at startup.\n\
\n Attributes:\n layout: Notebook layout config.\n resumed:\
\ Whether resumed from previous session.\n ui_values: Previous UI element\
\ values if resumed.\n last_executed_code: Last executed code per cell\
\ if resumed.\n last_execution_time: Last execution time per cell if\
\ resumed.\n app_config: Application configuration.\n kiosk:\
\ Whether running in kiosk mode.\n capabilities: Available kernel capabilities.\n\
\ auto_instantiated: Whether cells already executed (run mode).\n \
\ stable_session_id: Server-owned Session identity that survives\n \
\ browser reconnects. None where no server Session exists."
properties:
app_config:
$ref: '#/components/schemas/_AppConfig'
auto_instantiated:
default: false
type: boolean
capabilities:
$ref: '#/components/schemas/KernelCapabilitiesNotification'
consumer_capabilities:
$ref: '#/components/schemas/ConsumerCapabilities'
kiosk:
type: boolean
last_executed_code:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
last_execution_time:
anyOf:
- additionalProperties:
type: number
type: object
- type: 'null'
layout:
anyOf:
- $ref: '#/components/schemas/LayoutConfig'
- type: 'null'
op:
enum:
- kernel-ready
resumed:
type: boolean
stable_session_id:
anyOf:
- type: string
- type: 'null'
default: null
ui_values:
anyOf:
- type: object
- type: 'null'
required:
- op
- layout
- resumed
- ui_values
- last_executed_code
- last_execution_time
- app_config
- kiosk
- capabilities
- consumer_capabilities
title: KernelReadyNotification
type: object
KernelStartupErrorNotification:
description: "Kernel failed to start.\n\n Attributes:\n error: Error\
\ message describing failure."
properties:
error:
type: string
op:
enum:
- kernel-startup-error
required:
- op
- error
title: KernelStartupErrorNotification
type: object
KernelStatusResponse:
properties:
state:
enum:
- idle
- running
- stopped
required:
- state
title: KernelStatusResponse
type: object
KeymapConfig:
description: "Configuration for keymaps.\n\n **Keys.**\n\n - `preset`:\
\ one of `\"default\"` or `\"vim\"`\n - `overrides`: a dict of keymap actions\
\ to their keymap override\n - `vimrc`: path to a vimrc file to load keymaps\
\ from\n - `destructive_delete`: if `True`, allows deleting cells with\
\ content."
properties:
destructive_delete:
type: boolean
overrides:
additionalProperties:
type: string
type: object
preset:
enum:
- default
- vim
vimrc:
anyOf:
- type: string
- type: 'null'
required:
- preset
title: KeymapConfig
type: object
KnownUnions:
deprecated: true
description: Use the named NotificationMessage, ClientCommand, MarimoError,
and DataType schemas directly.
properties:
command:
$ref: '#/components/schemas/ClientCommand'
data_type:
$ref: '#/components/schemas/DataType'
error:
$ref: '#/components/schemas/MarimoError'
notification:
$ref: '#/components/schemas/NotificationMessage'
required:
- notification
- command
- error
- data_type
title: KnownUnions
type: object
LanguageServersConfig:
description: "Configuration options for language servers.\n\n **Keys.**\n\
\n - `pylsp`: the pylsp config\n - `basedpyright`: the basedpyright\
\ config\n - `ty`: the ty config\n - `pyrefly`: the pyrefly config"
properties:
basedpyright:
$ref: '#/components/schemas/BasedpyrightServerConfig'
pylsp:
$ref: '#/components/schemas/PythonLanguageServerConfig'
pyrefly:
$ref: '#/components/schemas/PyreflyLanguageServerConfig'
ty:
$ref: '#/components/schemas/TyLanguageServerConfig'
required: []
title: LanguageServersConfig
type: object
LayoutConfig:
properties:
data:
type: object
type:
type: string
required:
- type
- data
title: LayoutConfig
type: object
LazyImportError:
properties:
lineno:
anyOf:
- type: integer
- type: 'null'
default: null
msg:
type: string
type:
enum:
- lazy-import
required:
- type
- msg
title: LazyImportError
type: object
LintConfig:
description: "Configuration for lint rule selection.\n\n Follows ruff-inspired\
\ semantics for selecting which rules to run\n during `marimo check`.\n\
\n **Keys.**\n\n - `select`: list of rule code prefixes that replaces\
\ the default\n enabled set. Use `\"ALL\"` to select all rules.\n \
\ Example: `[\"MB\", \"MR001\"]`\n - `ignore`: list of rule code prefixes\
\ to remove from the\n enabled set."
properties:
ignore:
items:
type: string
type: array
select:
items:
type: string
type: array
required: []
title: LintConfig
type: object
ListDataSourceConnectionCommand:
description: "List data source schemas.\n\n Retrieves available schemas for\
\ a data source engine.\n\n Attributes:\n engine: Data source engine\
\ identifier."
properties:
engine:
type: string
type:
enum:
- list-data-source-connection
required:
- type
- engine
title: ListDataSourceConnectionCommand
type: object
ListDataSourceConnectionRequest:
properties:
engine:
type: string
required:
- engine
title: ListDataSourceConnectionRequest
type: object
ListPackagesResponse:
properties:
packages:
items:
$ref: '#/components/schemas/PackageDescription'
type: array
required:
- packages
title: ListPackagesResponse
type: object
ListSQLSchemasCommand:
description: "List schemas in an SQL database.\n\n Retrieves names of all\
\ schemas in a database. Used by the SQL editor for\n schema selection.\n\
\n Attributes:\n request_id: Unique identifier for this request.\n\
\ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
\ database: Database to query.\n schema_path: Parent schema path\
\ whose child schemas to list.\n Empty lists the database's top-level\
\ schemas."
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schemaPath:
default: []
items:
type: string
type: array
type:
enum:
- list-sql-schemas
required:
- type
- requestId
- engine
- database
title: ListSQLSchemasCommand
type: object
ListSQLSchemasRequest:
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schemaPath:
default: []
items:
type: string
type: array
required:
- requestId
- engine
- database
title: ListSQLSchemasRequest
type: object
ListSQLTablesCommand:
description: "List tables in an SQL schema.\n\n Retrieves names of all tables\
\ and views in a schema. Used by the SQL\n editor for table selection.\n\
\n Attributes:\n request_id: Unique identifier for this request.\n\
\ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
\ database: Database to query.\n schema: Schema to list tables\
\ from.\n schema_path: Path of nested schemas (relative to `database`)\
\ for\n catalogs with nested schemas. Empty for the top level."
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schema:
type: string
schemaPath:
default: []
items:
type: string
type: array
type:
enum:
- list-sql-tables
required:
- type
- requestId
- engine
- database
- schema
title: ListSQLTablesCommand
type: object
ListSQLTablesRequest:
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schema:
type: string
schemaPath:
default: []
items:
type: string
type: array
required:
- requestId
- engine
- database
- schema
title: ListSQLTablesRequest
type: object
ListSecretKeysCommand:
description: "List available secret keys.\n\n Retrieves secret names without\
\ exposing values.\n\n Attributes:\n request_id: Unique identifier\
\ for this request."
properties:
requestId:
$ref: '#/components/schemas/RequestId'
type:
enum:
- list-secret-keys
required:
- type
- requestId
title: ListSecretKeysCommand
type: object
ListSecretKeysRequest:
properties:
requestId:
$ref: '#/components/schemas/RequestId'
required:
- requestId
title: ListSecretKeysRequest
type: object
ListSecretKeysResponse:
properties:
keys:
items:
$ref: '#/components/schemas/SecretKeysWithProvider'
type: array
required:
- keys
title: ListSecretKeysResponse
type: object
LspHealthResponse:
description: Aggregated health response for all LSP servers.
properties:
servers:
items:
$ref: '#/components/schemas/LspServerHealth'
type: array
status:
enum:
- degraded
- healthy
- unhealthy
required:
- status
- servers
title: LspHealthResponse
type: object
LspRestartRequest:
description: Request to restart LSP servers.
properties:
serverIds:
anyOf:
- items:
type: string
type: array
- type: 'null'
default: null
required: []
title: LspRestartRequest
type: object
LspRestartResponse:
description: Response from restart operation.
properties:
errors:
additionalProperties:
type: string
default: {}
type: object
restarted:
items:
type: string
type: array
success:
type: boolean
required:
- success
- restarted
title: LspRestartResponse
type: object
LspServerHealth:
description: "Health status for a single LSP server.\n\n Status meanings:\n\
\ - starting: process launched, initializing\n - running: healthy and\
\ responsive to pings\n - stopped: not running (never started or cleanly\
\ stopped)\n - crashed: exited with non-zero code\n - unresponsive:\
\ process alive but not responding to pings"
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
lastPingMs:
anyOf:
- type: number
- type: 'null'
default: null
port:
type: integer
serverId:
type: string
startedAt:
anyOf:
- type: number
- type: 'null'
default: null
status:
enum:
- crashed
- running
- starting
- stopped
- unresponsive
required:
- serverId
- status
- port
title: LspServerHealth
type: object
MCPConfig:
description: 'Configuration for MCP servers
Note: the field name `mcpServers` is camelCased to match MCP server
config conventions used by popular AI applications (e.g. Cursor, Claude Desktop,
etc.)'
properties:
mcpServers:
additionalProperties:
type: object
type: object
presets:
items:
enum:
- context7
- marimo
type: array
required:
- mcpServers
title: MCPConfig
type: object
MCPRefreshResponse:
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
servers:
additionalProperties:
type: boolean
default: {}
type: object
success:
type: boolean
required:
- success
title: MCPRefreshResponse
type: object
MCPStatusResponse:
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
servers:
additionalProperties:
enum:
- connected
- disconnected
- failed
- pending
default: {}
type: object
status:
enum:
- error
- ok
- partial
required:
- status
title: MCPStatusResponse
type: object
MarimoAncestorPreventedError:
properties:
blamed_cell:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
msg:
type: string
raising_cell:
$ref: '#/components/schemas/CellId'
type:
enum:
- ancestor-prevented
required:
- type
- msg
- raising_cell
- blamed_cell
title: MarimoAncestorPreventedError
type: object
MarimoAncestorStoppedError:
properties:
msg:
type: string
raising_cell:
$ref: '#/components/schemas/CellId'
type:
enum:
- ancestor-stopped
required:
- type
- msg
- raising_cell
title: MarimoAncestorStoppedError
type: object
MarimoConfig:
description: Configuration for the marimo editor
properties:
ai:
$ref: '#/components/schemas/AiConfig'
cache:
$ref: '#/components/schemas/CacheConfig'
completion:
$ref: '#/components/schemas/CompletionConfig'
datasources:
$ref: '#/components/schemas/DatasourcesConfig'
diagnostics:
$ref: '#/components/schemas/DiagnosticsConfig'
display:
$ref: '#/components/schemas/DisplayConfig'
experimental:
type: object
file_browser:
$ref: '#/components/schemas/FileBrowserConfig'
formatting:
$ref: '#/components/schemas/FormattingConfig'
keymap:
$ref: '#/components/schemas/KeymapConfig'
language_servers:
$ref: '#/components/schemas/LanguageServersConfig'
lint:
$ref: '#/components/schemas/LintConfig'
mcp:
$ref: '#/components/schemas/MCPConfig'
package_management:
$ref: '#/components/schemas/PackageManagementConfig'
runtime:
$ref: '#/components/schemas/RuntimeConfig'
save:
$ref: '#/components/schemas/SaveConfig'
server:
$ref: '#/components/schemas/ServerConfig'
sharing:
$ref: '#/components/schemas/SharingConfig'
signing:
$ref: '#/components/schemas/SigningConfig'
snippets:
$ref: '#/components/schemas/SnippetsConfig'
venv:
$ref: '#/components/schemas/VenvConfig'
required:
- completion
- display
- formatting
- keymap
- package_management
- runtime
- save
- server
title: MarimoConfig
type: object
MarimoError:
anyOf:
- $ref: '#/components/schemas/SetupRootError'
- $ref: '#/components/schemas/CycleError'
- $ref: '#/components/schemas/MultipleDefinitionError'
- $ref: '#/components/schemas/ImportStarError'
- $ref: '#/components/schemas/LazyImportError'
- $ref: '#/components/schemas/MarimoAncestorStoppedError'
- $ref: '#/components/schemas/MarimoAncestorPreventedError'
- $ref: '#/components/schemas/MarimoExceptionRaisedError'
- $ref: '#/components/schemas/MarimoStrictExecutionError'
- $ref: '#/components/schemas/MarimoInterruptionError'
- $ref: '#/components/schemas/MarimoSyntaxError'
- $ref: '#/components/schemas/MarimoInternalError'
- $ref: '#/components/schemas/MarimoSQLError'
- $ref: '#/components/schemas/UnknownError'
discriminator:
mapping:
ancestor-prevented: '#/components/schemas/MarimoAncestorPreventedError'
ancestor-stopped: '#/components/schemas/MarimoAncestorStoppedError'
cycle: '#/components/schemas/CycleError'
exception: '#/components/schemas/MarimoExceptionRaisedError'
import-star: '#/components/schemas/ImportStarError'
internal: '#/components/schemas/MarimoInternalError'
interruption: '#/components/schemas/MarimoInterruptionError'
lazy-import: '#/components/schemas/LazyImportError'
multiple-defs: '#/components/schemas/MultipleDefinitionError'
setup-refs: '#/components/schemas/SetupRootError'
sql-error: '#/components/schemas/MarimoSQLError'
strict-exception: '#/components/schemas/MarimoStrictExecutionError'
syntax: '#/components/schemas/MarimoSyntaxError'
unknown: '#/components/schemas/UnknownError'
propertyName: type
MarimoExceptionRaisedError:
properties:
exception_type:
type: string
msg:
type: string
raising_cell:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
traceback:
anyOf:
- type: string
- type: 'null'
default: null
type:
enum:
- exception
required:
- type
- msg
- exception_type
- raising_cell
title: MarimoExceptionRaisedError
type: object
MarimoFile:
properties:
initializationId:
anyOf:
- type: string
- type: 'null'
default: null
lastModified:
anyOf:
- type: number
- type: 'null'
default: null
name:
type: string
path:
type: string
sessionId:
anyOf:
- $ref: '#/components/schemas/SessionId'
- type: 'null'
default: null
required:
- name
- path
title: MarimoFile
type: object
MarimoInternalError:
description: 'An internal error that should be hidden from the user.
The error is logged to the console and then a new error is broadcasted
such that the data is hidden.
They can be linked back to the original error by the error_id.'
properties:
error_id:
type: string
msg:
default: ''
type: string
type:
enum:
- internal
required:
- type
- error_id
title: MarimoInternalError
type: object
MarimoInterruptionError:
properties:
type:
enum:
- interruption
required:
- type
title: MarimoInterruptionError
type: object
MarimoSQLError:
description: SQL-specific error with enhanced metadata for debugging.
properties:
hint:
anyOf:
- type: string
- type: 'null'
default: null
msg:
type: string
node_col_offset:
default: 0
type: integer
node_lineno:
default: 0
type: integer
sql_col:
anyOf:
- type: integer
- type: 'null'
default: null
sql_line:
anyOf:
- type: integer
- type: 'null'
default: null
sql_statement:
type: string
type:
enum:
- sql-error
required:
- type
- msg
- sql_statement
title: MarimoSQLError
type: object
MarimoStrictExecutionError:
properties:
blamed_cell:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
msg:
type: string
ref:
type: string
type:
enum:
- strict-exception
required:
- type
- msg
- ref
- blamed_cell
title: MarimoStrictExecutionError
type: object
MarimoSyntaxError:
properties:
lineno:
anyOf:
- type: integer
- type: 'null'
default: null
msg:
type: string
type:
enum:
- syntax
required:
- type
- msg
title: MarimoSyntaxError
type: object
MissingPackageAlertNotification:
description: "Alert for missing packages with install option.\n\n Attributes:\n\
\ packages: Missing package names.\n isolated: Whether auto-install\
\ is possible in this environment.\n source: Which Python environment\
\ to install into. \"kernel\" (default)\n installs in the kernel's\
\ venv; \"server\" installs in the\n server's own Python env\
\ (e.g. for formatter tools like ruff)."
properties:
isolated:
type: boolean
op:
enum:
- missing-package-alert
packages:
items:
type: string
type: array
source:
default: kernel
enum:
- kernel
- server
required:
- op
- packages
- isolated
title: MissingPackageAlertNotification
type: object
ModelClose:
description: Widget destruction.
properties:
method:
enum:
- close
required:
- method
title: ModelClose
type: object
ModelCommand:
description: "Widget model message command.\n\n Handles widget model communication\
\ between frontend and backend.\n\n Attributes:\n model_id: Widget\
\ model identifier.\n message: Model message (update or custom).\n\
\ buffers: Base64-encoded binary buffers.\n token: Unique identifier\
\ for deduplication across dual queues."
properties:
buffers:
items:
$ref: '#/components/schemas/Base64String'
type: array
message:
anyOf:
- $ref: '#/components/schemas/ModelUpdateMessage'
- $ref: '#/components/schemas/ModelCustomMessage'
discriminator:
mapping:
custom: '#/components/schemas/ModelCustomMessage'
update: '#/components/schemas/ModelUpdateMessage'
propertyName: method
modelId:
$ref: '#/components/schemas/WidgetModelId'
token:
type: string
type:
enum:
- model
required:
- type
- modelId
- message
- buffers
title: ModelCommand
type: object
ModelCustom:
description: Custom application message.
properties:
buffers:
items:
$ref: '#/components/schemas/Base64String'
type: array
content: {}
method:
enum:
- custom
required:
- method
- content
- buffers
title: ModelCustom
type: object
ModelCustomMessage:
description: "Custom widget message.\n\n Attributes:\n content: Arbitrary\
\ content for the custom message."
properties:
content: {}
method:
enum:
- custom
required:
- method
- content
title: ModelCustomMessage
type: object
ModelLifecycleNotification:
description: "Widget model lifecycle message.\n\n Mirrors the Jupyter widget\
\ comm protocol with open/update/custom/close.\n\n Attributes:\n \
\ model_id: Widget model identifier.\n message: The lifecycle message\
\ (open/update/custom/close)."
properties:
message:
anyOf:
- $ref: '#/components/schemas/ModelOpen'
- $ref: '#/components/schemas/ModelUpdate'
- $ref: '#/components/schemas/ModelCustom'
- $ref: '#/components/schemas/ModelClose'
discriminator:
mapping:
close: '#/components/schemas/ModelClose'
custom: '#/components/schemas/ModelCustom'
open: '#/components/schemas/ModelOpen'
update: '#/components/schemas/ModelUpdate'
propertyName: method
model_id:
$ref: '#/components/schemas/WidgetModelId'
op:
enum:
- model-lifecycle
required:
- op
- model_id
- message
title: ModelLifecycleNotification
type: object
ModelOpen:
description: "Initial widget state on creation.\n\n For anywidgets, the widget's\
\ ESM does not travel in `state`: the\n comm strips `_esm` and sends an\
\ `EsmSpec` instead. `None` for\n models with no ESM (e.g. traditional\
\ ipywidgets).\n\n Attributes:\n state: Initial trait values, minus\
\ `_esm`.\n buffer_paths: Paths into `state` whose binary values were\n\
\ extracted into `buffers`.\n buffers: Binary payloads,\
\ parallel to `buffer_paths`.\n esm_spec: Where to import this widget's\
\ ESM from."
properties:
buffer_paths:
items:
items:
anyOf:
- type: string
- type: integer
type: array
type: array
buffers:
items:
$ref: '#/components/schemas/Base64String'
type: array
esm_spec:
anyOf:
- $ref: '#/components/schemas/EsmSpec'
- type: 'null'
default: null
method:
enum:
- open
state:
type: object
required:
- method
- state
- buffer_paths
- buffers
title: ModelOpen
type: object
ModelRequest:
properties:
buffers:
items:
$ref: '#/components/schemas/Base64String'
type: array
message:
anyOf:
- $ref: '#/components/schemas/ModelUpdateMessage'
- $ref: '#/components/schemas/ModelCustomMessage'
discriminator:
mapping:
custom: '#/components/schemas/ModelCustomMessage'
update: '#/components/schemas/ModelUpdateMessage'
propertyName: method
modelId:
$ref: '#/components/schemas/WidgetModelId'
token:
type: string
required:
- modelId
- message
- buffers
title: ModelRequest
type: object
ModelUpdate:
description: "State sync - changed traits only.\n\n Attributes:\n \
\ state: Changed trait values, minus `_esm` (see `ModelOpen`).\n buffer_paths:\
\ Paths into `state` whose binary values were\n extracted into\
\ `buffers`.\n buffers: Binary payloads, parallel to `buffer_paths`.\n\
\ esm_spec: Present only when the widget's `_esm` changed on a\n \
\ live model (hot reload, edit mode only). A spec whose\n \
\ `hash` differs from the current one tells the frontend the\n \
\ widget's code changed and views must be rebuilt."
properties:
buffer_paths:
items:
items:
anyOf:
- type: string
- type: integer
type: array
type: array
buffers:
items:
$ref: '#/components/schemas/Base64String'
type: array
esm_spec:
anyOf:
- $ref: '#/components/schemas/EsmSpec'
- type: 'null'
default: null
method:
enum:
- update
state:
type: object
required:
- method
- state
- buffer_paths
- buffers
title: ModelUpdate
type: object
ModelUpdateMessage:
description: "Widget model state update message.\n\n Attributes:\n \
\ state: Model state updates.\n buffer_paths: Paths within state dict\
\ pointing to binary buffers."
properties:
bufferPaths:
items:
items:
anyOf:
- type: string
- type: integer
type: array
type: array
method:
enum:
- update
state:
type: object
required:
- method
- state
- bufferPaths
title: ModelUpdateMessage
type: object
MoveCell:
description: Reposition a cell in the notebook.
properties:
after:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
default: null
before:
anyOf:
- $ref: '#/components/schemas/CellId'
- type: 'null'
default: null
cellId:
$ref: '#/components/schemas/CellId'
type:
enum:
- move-cell
required:
- type
- cellId
title: MoveCell
type: object
MultipleDefinitionError:
properties:
cells:
items:
$ref: '#/components/schemas/CellId'
type: array
name:
type: string
type:
enum:
- multiple-defs
required:
- type
- name
- cells
title: MultipleDefinitionError
type: object
NotebookCell:
description: "A single cell in the document. Mutable \u2014 owned by the document.\n\
\n `version` increments on each `SetCode` that actually changes\n `code`.\
\ Other property changes don't bump it."
properties:
code:
type: string
config:
$ref: '#/components/schemas/CellConfig'
id:
$ref: '#/components/schemas/CellId'
name:
type: string
version:
default: 0
type: integer
required:
- id
- code
- name
- config
title: NotebookCell
type: object
NotebookDocumentTransactionNotification:
description: "Broadcasts an applied transaction to the frontend.\n\n Sent\
\ by the session when the document changes (from any source).\n The frontend\
\ applies the ops to update its local state."
properties:
op:
enum:
- notebook-document-transaction
transaction:
$ref: '#/components/schemas/Transaction'
required:
- op
- transaction
title: NotebookDocumentTransactionNotification
type: object
NotificationMessage:
anyOf:
- $ref: '#/components/schemas/CellNotification'
- $ref: '#/components/schemas/ExecutionNotification'
- $ref: '#/components/schemas/FunctionCallResultNotification'
- $ref: '#/components/schemas/UIElementMessageNotification'
- $ref: '#/components/schemas/ModelLifecycleNotification'
- $ref: '#/components/schemas/RemoveUIElementsNotification'
- $ref: '#/components/schemas/ReloadNotification'
- $ref: '#/components/schemas/ReconnectedNotification'
- $ref: '#/components/schemas/InterruptedNotification'
- $ref: '#/components/schemas/CompletedRunNotification'
- $ref: '#/components/schemas/KernelReadyNotification'
- $ref: '#/components/schemas/CompletionResultNotification'
- $ref: '#/components/schemas/AlertNotification'
- $ref: '#/components/schemas/BannerNotification'
- $ref: '#/components/schemas/MissingPackageAlertNotification'
- $ref: '#/components/schemas/EnvironmentOperationNotification'
- $ref: '#/components/schemas/EnvironmentStateNotification'
- $ref: '#/components/schemas/StartupLogsNotification'
- $ref: '#/components/schemas/StartupProgressNotification'
- $ref: '#/components/schemas/KernelStartupErrorNotification'
- $ref: '#/components/schemas/VariablesNotification'
- $ref: '#/components/schemas/VariableValuesNotification'
- $ref: '#/components/schemas/QueryParamsSetNotification'
- $ref: '#/components/schemas/QueryParamsAppendNotification'
- $ref: '#/components/schemas/QueryParamsDeleteNotification'
- $ref: '#/components/schemas/QueryParamsClearNotification'
- $ref: '#/components/schemas/DatasetsNotification'
- $ref: '#/components/schemas/DataColumnPreviewNotification'
- $ref: '#/components/schemas/SQLTablePreviewNotification'
- $ref: '#/components/schemas/SQLTableListPreviewNotification'
- $ref: '#/components/schemas/SQLSchemaListPreviewNotification'
- $ref: '#/components/schemas/DataSourceConnectionsNotification'
- $ref: '#/components/schemas/DataSourceDiscoveryResultNotification'
- $ref: '#/components/schemas/ValidateSQLResultNotification'
- $ref: '#/components/schemas/StorageNamespacesNotification'
- $ref: '#/components/schemas/StorageEntriesNotification'
- $ref: '#/components/schemas/StorageDownloadReadyNotification'
- $ref: '#/components/schemas/SecretKeysResultNotification'
- $ref: '#/components/schemas/CacheClearedNotification'
- $ref: '#/components/schemas/CacheInfoNotification'
- $ref: '#/components/schemas/FocusCellNotification'
- $ref: '#/components/schemas/ActiveLineNotification'
- $ref: '#/components/schemas/NotebookDocumentTransactionNotification'
- $ref: '#/components/schemas/ConsumerCapabilitiesNotification'
discriminator:
mapping:
active-line: '#/components/schemas/ActiveLineNotification'
alert: '#/components/schemas/AlertNotification'
banner: '#/components/schemas/BannerNotification'
cache-cleared: '#/components/schemas/CacheClearedNotification'
cache-info: '#/components/schemas/CacheInfoNotification'
cell-op: '#/components/schemas/CellNotification'
completed-run: '#/components/schemas/CompletedRunNotification'
completion-result: '#/components/schemas/CompletionResultNotification'
consumer-capabilities: '#/components/schemas/ConsumerCapabilitiesNotification'
data-column-preview: '#/components/schemas/DataColumnPreviewNotification'
data-source-connections: '#/components/schemas/DataSourceConnectionsNotification'
data-source-discovery-result: '#/components/schemas/DataSourceDiscoveryResultNotification'
datasets: '#/components/schemas/DatasetsNotification'
environment-operation: '#/components/schemas/EnvironmentOperationNotification'
environment-state: '#/components/schemas/EnvironmentStateNotification'
execution: '#/components/schemas/ExecutionNotification'
focus-cell: '#/components/schemas/FocusCellNotification'
function-call-result: '#/components/schemas/FunctionCallResultNotification'
interrupted: '#/components/schemas/InterruptedNotification'
kernel-ready: '#/components/schemas/KernelReadyNotification'
kernel-startup-error: '#/components/schemas/KernelStartupErrorNotification'
missing-package-alert: '#/components/schemas/MissingPackageAlertNotification'
model-lifecycle: '#/components/schemas/ModelLifecycleNotification'
notebook-document-transaction: '#/components/schemas/NotebookDocumentTransactionNotification'
query-params-append: '#/components/schemas/QueryParamsAppendNotification'
query-params-clear: '#/components/schemas/QueryParamsClearNotification'
query-params-delete: '#/components/schemas/QueryParamsDeleteNotification'
query-params-set: '#/components/schemas/QueryParamsSetNotification'
reconnected: '#/components/schemas/ReconnectedNotification'
reload: '#/components/schemas/ReloadNotification'
remove-ui-elements: '#/components/schemas/RemoveUIElementsNotification'
secret-keys-result: '#/components/schemas/SecretKeysResultNotification'
send-ui-element-message: '#/components/schemas/UIElementMessageNotification'
sql-schema-list-preview: '#/components/schemas/SQLSchemaListPreviewNotification'
sql-table-list-preview: '#/components/schemas/SQLTableListPreviewNotification'
sql-table-preview: '#/components/schemas/SQLTablePreviewNotification'
startup-logs: '#/components/schemas/StartupLogsNotification'
startup-progress: '#/components/schemas/StartupProgressNotification'
storage-download-ready: '#/components/schemas/StorageDownloadReadyNotification'
storage-entries: '#/components/schemas/StorageEntriesNotification'
storage-namespaces: '#/components/schemas/StorageNamespacesNotification'
validate-sql-result: '#/components/schemas/ValidateSQLResultNotification'
variable-values: '#/components/schemas/VariableValuesNotification'
variables: '#/components/schemas/VariablesNotification'
propertyName: op
OpenAiConfig:
description: "Configuration options for OpenAI or OpenAI-compatible services.\n\
\n **Keys.**\n\n - `api_key`: the OpenAI API key or an `env:` reference\n\
\ - `base_url`: the base URL for the API\n - `project`: the project\
\ ID for the OpenAI API\n - `ssl_verify` : Boolean argument for httpx passed\
\ to open ai client. httpx defaults to true, but some use cases to let users\
\ override to False in some testing scenarios\n - `ca_bundle_path`: custom\
\ ca bundle to be used for verifying SSL certificates. Used to create custom\
\ SSL context for httpx client\n - `client_pem` : custom path of a client\
\ .pem cert used for verifying identity of client server\n - `extra_headers`:\
\ extra headers to be passed to the OpenAI client"
properties:
api_key:
type: string
base_url:
type: string
ca_bundle_path:
type: string
client_pem:
type: string
extra_headers:
additionalProperties:
type: string
type: object
model:
type: string
project:
type: string
ssl_verify:
type: boolean
required: []
title: OpenAiConfig
type: object
OpenGraphMetadata:
description: "OpenGraph-style metadata for a notebook.\n\n The `image` field\
\ may be either:\n - a relative path (typically under `__marimo__/`), or\n\
\ - an absolute HTTPS URL."
properties:
description:
anyOf:
- type: string
- type: 'null'
default: null
image:
anyOf:
- type: string
- type: 'null'
default: null
title:
anyOf:
- type: string
- type: 'null'
default: null
required: []
title: OpenGraphMetadata
type: object
OpenTutorialRequest:
properties:
tutorialId:
anyOf:
- enum:
- dataflow
- external-dependencies
- fileformat
- for-jupyter-users
- intro
- layout
- markdown
- plots
- sql
- ui
- enum:
- markdown-format
required:
- tutorialId
title: OpenTutorialRequest
type: object
OperationCancelled:
additionalProperties: false
properties:
kind:
enum:
- cancelled
required:
- kind
title: OperationCancelled
type: object
OperationFailed:
additionalProperties: false
properties:
error:
type: string
kind:
enum:
- failed
required:
- kind
- error
title: OperationFailed
type: object
OperationRestartRequired:
additionalProperties: false
properties:
kind:
enum:
- restart-required
reason:
type: string
required:
- kind
- reason
title: OperationRestartRequired
type: object
OperationRunning:
additionalProperties: false
properties:
kind:
enum:
- running
required:
- kind
title: OperationRunning
type: object
OperationSucceeded:
additionalProperties: false
properties:
kind:
enum:
- succeeded
required:
- kind
title: OperationSucceeded
type: object
PackageDescription:
properties:
name:
type: string
version:
type: string
required:
- name
- version
title: PackageDescription
type: object
PackageManagementConfig:
description: "Configuration options for package management.\n\n **Keys.**\n\
\n - `manager`: the package manager to use"
properties:
manager:
enum:
- pip
- pixi
- poetry
- rye
- uv
required:
- manager
title: PackageManagementConfig
type: object
PackageManagerContext:
properties:
kind:
enum:
- package-manager
name:
type: string
required:
- kind
- name
title: PackageManagerContext
type: object
PackageOperationResponse:
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
restartRequired:
default: false
type: boolean
success:
type: boolean
required:
- success
title: PackageOperationResponse
type: object
PreviewDatasetColumnCommand:
description: "Preview a dataset column.\n\n Retrieves and displays data from\
\ a single column (dataframe or SQL table).\n Used by the data explorer\
\ UI.\n\n Attributes:\n source_type: Data source type ('dataframe',\
\ 'sql', etc.).\n source: Source identifier (connection string or variable\
\ name).\n table_name: Table or dataframe variable name.\n column_name:\
\ Column to preview.\n fully_qualified_table_name: Full database.schema.table\
\ name for SQL."
properties:
columnName:
type: string
fullyQualifiedTableName:
anyOf:
- type: string
- type: 'null'
default: null
source:
type: string
sourceType:
enum:
- catalog
- connection
- duckdb
- local
tableName:
type: string
type:
enum:
- preview-dataset-column
required:
- type
- sourceType
- source
- tableName
- columnName
title: PreviewDatasetColumnCommand
type: object
PreviewDatasetColumnRequest:
properties:
columnName:
type: string
fullyQualifiedTableName:
anyOf:
- type: string
- type: 'null'
default: null
source:
type: string
sourceType:
enum:
- catalog
- connection
- duckdb
- local
tableName:
type: string
required:
- sourceType
- source
- tableName
- columnName
title: PreviewDatasetColumnRequest
type: object
PreviewSQLTableCommand:
description: "Preview SQL table details.\n\n Retrieves metadata and sample\
\ data for a table. Used by the SQL editor\n and data explorer.\n\n \
\ Attributes:\n request_id: Unique identifier for this request.\n \
\ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
\ database: Database containing the table.\n schema: Schema containing\
\ the table.\n table_name: Table to preview.\n schema_path:\
\ Path of nested schemas (relative to `database`) for\n catalogs\
\ with nested schemas. Empty for the top level."
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schema:
type: string
schemaPath:
default: []
items:
type: string
type: array
tableName:
type: string
type:
enum:
- preview-sql-table
required:
- type
- requestId
- engine
- database
- schema
- tableName
title: PreviewSQLTableCommand
type: object
PreviewSQLTableRequest:
properties:
database:
type: string
engine:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
schema:
type: string
schemaPath:
default: []
items:
type: string
type: array
tableName:
type: string
required:
- requestId
- engine
- database
- schema
- tableName
title: PreviewSQLTableRequest
type: object
PyreflyLanguageServerConfig:
description: 'Configuration options for Pyrefly Language Server.
Pyrefly handles completion, hover, go-to-definition, and diagnostics.'
properties:
enabled:
type: boolean
required: []
title: PyreflyLanguageServerConfig
type: object
PythonLanguageServerConfig:
description: 'Configuration options for Python Language Server.
pylsp handles completion, hover, go-to-definition, and diagnostics.'
properties:
enable_flake8:
type: boolean
enable_mypy:
type: boolean
enable_pydocstyle:
type: boolean
enable_pyflakes:
type: boolean
enable_pylint:
type: boolean
enable_ruff:
type: boolean
enabled:
type: boolean
required: []
title: PythonLanguageServerConfig
type: object
QueryParamsAppendNotification:
description: "Appends value to URL query parameter.\n\n Attributes:\n \
\ key: Query parameter key.\n value: Value to append."
properties:
key:
type: string
op:
enum:
- query-params-append
value:
type: string
required:
- op
- key
- value
title: QueryParamsAppendNotification
type: object
QueryParamsClearNotification:
description: Clears all URL query parameters.
properties:
op:
enum:
- query-params-clear
required:
- op
title: QueryParamsClearNotification
type: object
QueryParamsDeleteNotification:
description: "Deletes URL query parameter values.\n\n Attributes:\n \
\ key: Query parameter key.\n value: Specific value to delete. If\
\ None, deletes all values for key."
properties:
key:
type: string
op:
enum:
- query-params-delete
value:
anyOf:
- type: string
- type: 'null'
required:
- op
- key
- value
title: QueryParamsDeleteNotification
type: object
QueryParamsSetNotification:
description: "Sets URL query parameter, replacing existing values.\n\n Attributes:\n\
\ key: Query parameter key.\n value: Value(s) to set."
properties:
key:
type: string
op:
enum:
- query-params-set
value:
anyOf:
- type: string
- items:
type: string
type: array
required:
- op
- key
- value
title: QueryParamsSetNotification
type: object
ReadCodeResponse:
properties:
contents:
type: string
required:
- contents
title: ReadCodeResponse
type: object
RecentFilesResponse:
properties:
files:
items:
$ref: '#/components/schemas/MarimoFile'
type: array
required:
- files
title: RecentFilesResponse
type: object
ReconnectedNotification:
description: WebSocket reconnection confirmed.
properties:
op:
enum:
- reconnected
required:
- op
title: ReconnectedNotification
type: object
ReloadNotification:
description: Instructs frontend to reload the page.
properties:
op:
enum:
- reload
required:
- op
title: ReloadNotification
type: object
RemovePackageRequest:
properties:
group:
anyOf:
- type: string
- type: 'null'
default: null
package:
type: string
required:
- package
title: RemovePackageRequest
type: object
RemoveUIElementsNotification:
description: "Removes UI elements associated with a cell.\n\n Sent when cell\
\ is re-executed or deleted.\n\n Attributes:\n cell_id: Cell whose\
\ UI elements should be removed."
properties:
cell_id:
$ref: '#/components/schemas/CellId'
op:
enum:
- remove-ui-elements
required:
- op
- cell_id
title: RemoveUIElementsNotification
type: object
RenameNotebookRequest:
properties:
filename:
type: string
required:
- filename
title: RenameNotebookRequest
type: object
ReorderCells:
description: "Replace the full cell ordering.\n\n Cell IDs present in the\
\ document but missing from `cell_ids`\n are appended at the end. IDs not\
\ in the document are ignored."
properties:
cellIds:
items:
$ref: '#/components/schemas/CellId'
type: array
type:
enum:
- reorder-cells
required:
- type
- cellIds
title: ReorderCells
type: object
RequestId:
format: request-id
type: string
Revision:
properties:
execution:
description: Identifies an execution. Unique within the host.
minLength: 1
type: string
update:
description: How many times the value has been updated since it was produced.
Zero at binding.
minimum: 0
type: integer
required:
- execution
- update
title: Revision
type: object
RunningNotebooksResponse:
properties:
files:
items:
$ref: '#/components/schemas/MarimoFile'
type: array
required:
- files
title: RunningNotebooksResponse
type: object
RuntimeConfig:
description: "Configuration for runtime.\n\n **Keys.**\n\n - `auto_instantiate`:\
\ if `False`, cells won't automatically\n run on startup. This only\
\ applies when editing a notebook,\n and not when running as an application.\n\
\ The default is `True`.\n - `auto_reload`: if `lazy`, cells importing\
\ modified modules will marked\n as stale; if `autorun`, affected cells\
\ will be automatically run. similar\n to IPython's %autoreload extension\
\ but with more code intelligence.\n - `reactive_tests`: if `True`, marimo\
\ will automatically run pytest on cells containing only test functions and\
\ test classes.\n execution.\n - `on_cell_change`: if `lazy`, cells\
\ will be marked stale when their\n ancestors run but won't autorun;\
\ if `autorun`, cells will automatically\n run when their ancestors run.\n\
\ - `execution_type`: if `relaxed`, marimo will not clone cell declarations;\n\
\ if `strict` marimo will clone cell declarations by default, avoiding\n\
\ hidden potential state build up.\n - `watcher_on_save`: how to handle\
\ file changes when saving. `\"lazy\"` marks\n affected cells as stale,\
\ `\"autorun\"` automatically runs affected cells.\n - `output_max_bytes`:\
\ the maximum size in bytes of cell outputs; larger\n values may affect\
\ frontend performance\n - `serve_cached_sessions_in_apps`: if `True`,\
\ initialize applications with session cache.\n The default is `False`.\n\
\ - `std_stream_max_bytes`: the maximum size in bytes of console outputs;\n\
\ larger values may affect frontend performance\n - `pythonpath`:\
\ a list of directories to add to the Python search path.\n Directories\
\ will be added to the head of sys.path. Similar to the\n `PYTHONPATH`\
\ environment variable, the directories will be included in\n where\
\ Python will look for imported modules.\n - `dotenv`: a list of paths\
\ to `.env` files to load.\n If the file does not exist, it will be\
\ silently ignored. Relative\n paths resolve against the directory\
\ holding the `pyproject.toml`,\n or the notebook's directory when\
\ there is none. The default is\n `[\".env\"]`.\n - `default_sql_output`:\
\ the default output format for SQL queries. Can be one of:\n `\"auto\"\
`, `\"native\"`, `\"polars\"`, `\"lazy-polars\"`, or `\"pandas\"`.\n \
\ The default is `\"auto\"`.\n - `default_auto_download`: an Optional\
\ list of export types to automatically snapshot your notebook as:\n \
\ `html`, `markdown`, `ipynb`.\n The default is None.\n - `default_csv_encoding`:\
\ the default encoding for CSV exports.\n The default is `\"utf-8\"\
`.\n - `show_tracebacks`: if `True`, show detailed error tracebacks in\
\ run mode.\n When enabled, exceptions will display a clickable toast\
\ that opens a modal with the full traceback.\n The default is `False`."
properties:
auto_instantiate:
type: boolean
auto_reload:
enum:
- autorun
- lazy
- 'off'
default_auto_download:
items:
enum:
- html
- ipynb
- markdown
type: array
default_csv_encoding:
type: string
default_sql_output:
enum:
- auto
- lazy-polars
- native
- pandas
- polars
dotenv:
items:
type: string
type: array
on_cell_change:
enum:
- autorun
- lazy
output_max_bytes:
type: integer
pythonpath:
items:
type: string
type: array
reactive_tests:
type: boolean
serve_cached_sessions_in_apps:
type: boolean
show_tracebacks:
type: boolean
std_stream_max_bytes:
type: integer
watcher_on_save:
enum:
- autorun
- lazy
required:
- auto_instantiate
- auto_reload
- default_sql_output
- on_cell_change
- output_max_bytes
- reactive_tests
- std_stream_max_bytes
- watcher_on_save
title: RuntimeConfig
type: object
SQLDatabaseMetadata:
description: "SQL database metadata.\n\n Attributes:\n connection:\
\ Connection identifier.\n database: Database name.\n schema_path:\
\ Parent schema path the schemas belong under. Empty for\n the\
\ database's top level."
properties:
connection:
type: string
database:
type: string
schema_path:
default: []
items:
type: string
type: array
required:
- connection
- database
title: SQLDatabaseMetadata
type: object
SQLMetadata:
description: "SQL database and schema metadata.\n\n Attributes:\n \
\ connection: Connection identifier.\n database: Database name.\n \
\ schema: Schema name.\n schema_path: Path of nested schemas\
\ (relative to `database`). Empty\n for the top level."
properties:
connection:
type: string
database:
type: string
schema:
type: string
schema_path:
default: []
items:
type: string
type: array
type:
enum:
- sql-metadata
required:
- type
- connection
- database
- schema
title: SQLMetadata
type: object
SQLSchemaListPreviewNotification:
description: "List of SQL schemas in a database.\n\n Attributes:\n \
\ request_id: Request ID this responds to.\n metadata: Database and\
\ schema metadata.\n schemas: Schemas in database.\n error:\
\ Error message if failed."
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
metadata:
$ref: '#/components/schemas/SQLDatabaseMetadata'
op:
enum:
- sql-schema-list-preview
request_id:
$ref: '#/components/schemas/RequestId'
schemas:
default: []
items:
$ref: '#/components/schemas/Schema'
type: array
required:
- op
- request_id
- metadata
title: SQLSchemaListPreviewNotification
type: object
SQLTableListPreviewNotification:
description: "List of SQL tables in a schema.\n\n Attributes:\n request_id:\
\ Request ID this responds to.\n metadata: Database and schema metadata.\n\
\ tables: Tables in schema.\n error: Error message if failed."
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
metadata:
$ref: '#/components/schemas/SQLMetadata'
op:
enum:
- sql-table-list-preview
request_id:
$ref: '#/components/schemas/RequestId'
tables:
default: []
items:
$ref: '#/components/schemas/DataTable'
type: array
required:
- op
- request_id
- metadata
title: SQLTableListPreviewNotification
type: object
SQLTablePreviewNotification:
description: "SQL table preview.\n\n Attributes:\n request_id: Request\
\ ID this responds to.\n metadata: Database and schema metadata.\n\
\ table: Table data (None if error).\n error: Error message\
\ if failed."
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
metadata:
$ref: '#/components/schemas/SQLMetadata'
op:
enum:
- sql-table-preview
request_id:
$ref: '#/components/schemas/RequestId'
table:
anyOf:
- $ref: '#/components/schemas/DataTable'
- type: 'null'
required:
- op
- request_id
- metadata
- table
title: SQLTablePreviewNotification
type: object
SafeLiteralDiscoveryValue:
description: Non-sensitive metadata that is safe to send to the frontend.
properties:
kind:
enum:
- safe-literal
value:
type: string
required:
- kind
- value
title: SafeLiteralDiscoveryValue
type: object
SandboxPackageContext:
properties:
backend:
enum:
- pixi
- uv
kind:
enum:
- sandbox
required:
- kind
- backend
title: SandboxPackageContext
type: object
SandboxRequest:
properties:
fileKey:
anyOf:
- type: string
- type: 'null'
default: null
required: []
title: SandboxRequest
type: object
SandboxResponse:
properties:
backend:
anyOf:
- enum:
- pixi
- uv
- type: 'null'
filename:
anyOf:
- type: string
- type: 'null'
manifest:
anyOf:
- type: string
- type: 'null'
required:
- backend
- manifest
- filename
title: SandboxResponse
type: object
SaveAppConfigurationRequest:
properties:
config:
type: object
required:
- config
title: SaveAppConfigurationRequest
type: object
SaveConfig:
description: "Configuration for saving.\n\n **Keys.**\n\n - `autosave`:\
\ one of `\"off\"` or `\"after_delay\"`\n - `delay`: number of milliseconds\
\ to wait before autosaving\n - `format_on_save`: if `True`, format the\
\ code on save"
properties:
autosave:
enum:
- after_delay
- 'off'
autosave_delay:
type: integer
format_on_save:
type: boolean
required:
- autosave
- autosave_delay
- format_on_save
title: SaveConfig
type: object
SaveLayoutRequest:
description: The notebook's layout, written beside it; `None` removes it.
properties:
layout:
anyOf:
- type: object
- type: 'null'
default: null
required: []
title: SaveLayoutRequest
type: object
SaveUserConfigurationRequest:
properties:
config:
type: object
required:
- config
title: SaveUserConfigurationRequest
type: object
Schema:
description: "Represents a database schema and its tables.\n\nA schema may itself\
\ contain nested child schemas, e.g. for catalogs with\nhierarchical namespaces\
\ such as Iceberg (`top.nested.deep`).\n\nAttributes:\n name (str): The\
\ name of the schema.\n tables (List[DataTable]): Tables in this schema.\n\
\ tables_resolved (bool): True when `tables` has been enumerated\n \
\ False when table discovery was deferred. Defaults to True\n child_schemas\
\ (List[Schema]): Nested child schemas (sub-namespaces).\n child_schemas_resolved\
\ (bool): True when `child_schemas` has been\n enumerated. False when\
\ discovery was deferred. Defaults to True"
properties:
child_schemas:
default: []
items:
$ref: '#/components/schemas/Schema'
type: array
child_schemas_resolved:
default: true
type: boolean
name:
type: string
tables:
items:
$ref: '#/components/schemas/DataTable'
type: array
tables_resolved:
default: true
type: boolean
required:
- name
- tables
title: Schema
type: object
SchemaColumn:
properties:
name:
type: string
sampleValues:
type: array
type:
type: string
required:
- name
- type
- sampleValues
title: SchemaColumn
type: object
SchemaTable:
properties:
columns:
items:
$ref: '#/components/schemas/SchemaColumn'
type: array
name:
type: string
required:
- name
- columns
title: SchemaTable
type: object
SecretKeysResultNotification:
description: "Available secret keys from secret providers.\n\n Attributes:\n\
\ request_id: Request ID this responds to.\n secrets: Secret\
\ keys with provider info."
properties:
op:
enum:
- secret-keys-result
request_id:
$ref: '#/components/schemas/RequestId'
secrets:
items:
$ref: '#/components/schemas/SecretKeysWithProvider'
type: array
required:
- op
- request_id
- secrets
title: SecretKeysResultNotification
type: object
SecretKeysWithProvider:
properties:
keys:
items:
type: string
type: array
name:
type: string
provider:
enum:
- dotenv
- env
required:
- provider
- name
- keys
title: SecretKeysWithProvider
type: object
ServerConfig:
description: "Configuration for the server.\n\n **Keys.**\n\n - `browser`:\
\ the web browser to use. `\"default\"` or a browser registered\n with\
\ Python's webbrowser module (eg, `\"firefox\"` or `\"chrome\"`)\n - `follow_symlink`:\
\ if true, the server will follow symlinks it finds\n inside its static\
\ assets directory.\n - `disable_file_downloads`: if true, the file download\
\ button will be\n hidden in the file explorer.\n - `transport`:\
\ experimental. The transport used to stream kernel\n messages to the\
\ frontend, typically set with the\n `MARIMO_SERVER_TRANSPORT` environment\
\ variable. `\"websocket\"`\n (default) uses the `/ws` WebSocket endpoint;\
\ `\"sse\"` uses\n server-sent events over HTTP, for deployments behind\
\ proxies or\n services that do not support WebSockets. The terminal\
\ and LSP\n still require WebSockets."
properties:
browser:
anyOf:
- enum:
- default
- type: string
disable_file_downloads:
type: boolean
follow_symlink:
type: boolean
transport:
enum:
- sse
- websocket
required:
- browser
- follow_symlink
title: ServerConfig
type: object
SessionId:
format: session-id
type: string
SetBreakpointsRequest:
properties:
breakpoints:
additionalProperties:
items:
type: integer
type: array
type: object
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
required:
- breakpoints
title: SetBreakpointsRequest
type: object
SetCode:
description: Replace a cell's source code.
properties:
cellId:
$ref: '#/components/schemas/CellId'
code:
type: string
type:
enum:
- set-code
required:
- type
- cellId
- code
title: SetCode
type: object
SetConfig:
description: Replace a cell's config.
properties:
cellId:
$ref: '#/components/schemas/CellId'
column:
anyOf:
- type: integer
- type: 'null'
disabled:
type: boolean
expandOutput:
type: boolean
hideCode:
type: boolean
type:
enum:
- set-config
required:
- type
- cellId
- column
- disabled
- hideCode
- expandOutput
title: SetConfig
type: object
SetName:
description: Rename a cell.
properties:
cellId:
$ref: '#/components/schemas/CellId'
name:
type: string
type:
enum:
- set-name
required:
- type
- cellId
- name
title: SetName
type: object
SetupRootError:
properties:
edges_with_vars:
items:
items: false
maxItems: 3
minItems: 3
prefixItems:
- type: string
- items:
type: string
type: array
- type: string
type: array
type: array
type:
enum:
- setup-refs
required:
- type
- edges_with_vars
title: SetupRootError
type: object
SharingConfig:
description: "Configuration for sharing features.\n\n **Keys.**\n\n -\
\ `html`: if `False`, HTML sharing options will be hidden from the UI\n \
\ - `wasm`: if `False`, WebAssembly sharing options will be hidden from the\
\ UI\n - `molab`: if `False`, molab sharing options will be hidden from\
\ the UI"
properties:
html:
type: boolean
molab:
type: boolean
wasm:
type: boolean
required: []
title: SharingConfig
type: object
ShutdownSessionRequest:
properties:
sessionId:
$ref: '#/components/schemas/SessionId'
required:
- sessionId
title: ShutdownSessionRequest
type: object
SigningConfig:
description: "Cache-signing trust and identity.\n\n `trusted_signers` maps\
\ a key fingerprint (`\"SHA256:<base64>\"`) to an\n advisory label. Trusting\
\ a key allows arbitrary code execution from its\n holder on this machine\
\ \u2014 a cache restore is `pickle.loads` \u2014 so there is no\n lesser\
\ cache-only grant. `private_key_path` is this machine's signing\n identity;\
\ it is never serialized to the frontend."
properties:
private_key_path:
type: string
trusted_signers:
additionalProperties:
type: string
type: object
required: []
title: SigningConfig
type: object
Snippet:
properties:
sections:
items:
$ref: '#/components/schemas/SnippetSection'
type: array
title:
type: string
required:
- title
- sections
title: Snippet
type: object
SnippetSection:
properties:
code:
anyOf:
- type: string
- type: 'null'
default: null
html:
anyOf:
- type: string
- type: 'null'
default: null
id:
type: string
required:
- id
title: SnippetSection
type: object
Snippets:
properties:
snippets:
items:
$ref: '#/components/schemas/Snippet'
type: array
required:
- snippets
title: Snippets
type: object
SnippetsConfig:
description: "Configuration for snippets.\n\n **Keys.**\n\n - `custom_path`:\
\ the path to the custom snippets directory"
properties:
custom_paths:
items:
type: string
type: array
include_default_snippets:
type: boolean
required: []
title: SnippetsConfig
type: object
SqlCatalogCheckResult:
description: Result of running validation against the database.
properties:
error_message:
anyOf:
- type: string
- type: 'null'
success:
type: boolean
required:
- success
- error_message
title: SqlCatalogCheckResult
type: object
SqlParseError:
description: "Represents a single SQL parse error.\n\nAttributes:\n message\
\ (str): Description of the error.\n line (int): Line number where the\
\ error occurred (1-based).\n column (int): Column number where the error\
\ occurred (1-based).\n severity (Literal[\"error\", \"warning\"]): Severity\
\ of the error."
properties:
column:
type: integer
line:
type: integer
message:
type: string
severity:
enum:
- error
- warning
required:
- message
- line
- column
- severity
title: SqlParseError
type: object
SqlParseResult:
description: "Result of parsing an SQL query.\n\nAttributes:\n success (bool):\
\ True if parsing succeeded without errors.\n errors (list[SqlParseError]):\
\ List of parse errors (empty if success is True)."
properties:
errors:
items:
$ref: '#/components/schemas/SqlParseError'
type: array
success:
type: boolean
required:
- success
- errors
title: SqlParseResult
type: object
StartupLogsNotification:
description: "Streaming kernel startup logs.\n\n Attributes:\n content:\
\ Log content to display.\n status: Stream status (start/append/done)."
properties:
content:
type: string
op:
enum:
- startup-logs
status:
enum:
- append
- done
- start
required:
- op
- content
- status
title: StartupLogsNotification
type: object
StartupProgressNotification:
description: "Current startup phase and its output before the kernel is ready.\n\
\n Output appends within a phase. Snapshots replace it, and changing phases\n\
\ starts a new stream. Environment preparation logs belong to its operation."
properties:
log_mode:
enum:
- append
- replace
logs:
type: string
op:
enum:
- startup-progress
phase:
enum:
- preparing-environment
- starting-kernel
required:
- op
- phase
- logs
- log_mode
title: StartupProgressNotification
type: object
StdinRequest:
properties:
text:
type: string
required:
- text
title: StdinRequest
type: object
StorageDownloadReadyNotification:
description: "Signals that a storage file download is ready.\n\n The url\
\ may be a signed cloud URL (preferred) or a virtual file URL\n (fallback\
\ for backends that don't support signing).\n\n Attributes:\n request_id:\
\ Request ID this responds to.\n url: Signed or virtual-file URL to\
\ download from.\n filename: Suggested filename for the download.\n\
\ error: Error message if the download failed."
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
filename:
anyOf:
- type: string
- type: 'null'
default: null
op:
enum:
- storage-download-ready
request_id:
$ref: '#/components/schemas/RequestId'
url:
anyOf:
- type: string
- type: 'null'
default: null
required:
- op
- request_id
title: StorageDownloadReadyNotification
type: object
StorageDownloadRequest:
properties:
namespace:
type: string
path:
type: string
preview:
default: false
type: boolean
requestId:
$ref: '#/components/schemas/RequestId'
required:
- requestId
- namespace
- path
title: StorageDownloadRequest
type: object
StorageEntriesNotification:
description: "Result of a storage operation that returns entries.\n\n Attributes:\n\
\ request_id: Request ID this responds to.\n entries: Storage\
\ entries returned by the operation.\n namespace: Variable name of\
\ the storage backend.\n prefix: The prefix that was listed (set by\
\ list_entries).\n query: The search query that was used (set by search).\n\
\ next_page_token: Token for fetching the next page of entries.\n \
\ error: Error message if the operation failed."
properties:
entries:
items:
$ref: '#/components/schemas/StorageEntry'
type: array
error:
anyOf:
- type: string
- type: 'null'
default: null
namespace:
type: string
next_page_token:
anyOf:
- type: string
- type: 'null'
default: null
op:
enum:
- storage-entries
prefix:
anyOf:
- type: string
- type: 'null'
default: null
query:
anyOf:
- type: string
- type: 'null'
default: null
request_id:
$ref: '#/components/schemas/RequestId'
required:
- op
- request_id
- entries
- namespace
title: StorageEntriesNotification
type: object
StorageEntry:
description: "A storage entry is a file, directory, or object for external storage\
\ systems\n\n Attributes:\n path: The path of the storage entry.\n\
\ kind: The kind of the storage entry.\n size: The size of the\
\ storage entry.\n last_modified: The last modified time of the storage\
\ entry.\n metadata: The metadata of the storage entry.\n mime_type:\
\ The MIME type of the storage entry, or None for directories."
properties:
kind:
enum:
- directory
- file
- object
lastModified:
anyOf:
- type: number
- type: 'null'
metadata:
default: {}
type: object
mimeType:
anyOf:
- type: string
- type: 'null'
default: null
path:
type: string
size:
type: integer
required:
- path
- kind
- size
- lastModified
title: StorageEntry
type: object
StorageHidesWhen:
description: Hide this suggestion when a live storage namespace matches.
properties:
backendTypes:
items:
type: string
type: array
kind:
enum:
- storage
protocols:
items:
type: string
type: array
required:
- kind
- protocols
- backendTypes
title: StorageHidesWhen
type: object
StorageListEntriesRequest:
properties:
limit:
type: integer
namespace:
type: string
pageToken:
anyOf:
- type: string
- type: 'null'
default: null
prefix:
anyOf:
- type: string
- type: 'null'
default: null
requestId:
$ref: '#/components/schemas/RequestId'
required:
- requestId
- namespace
- limit
title: StorageListEntriesRequest
type: object
StorageNamespace:
description: "Represents external storage systems (filesystems and object storage)\n\
\n Attributes:\n name: The variable name of the storage namespace.\n\
\ display_name: The display name of the storage namespace.\n \
\ protocol: The protocol of the storage namespace. E.g. s3, gcs, azure, http,\
\ file, in-memory.\n root_path: The root path of the storage namespace.\n\
\ backend_type: The type of the storage backend (fsspec or obstore)\n\
\ storage_entries: The storage entries in the storage namespace."
properties:
backendType:
enum:
- fsspec
- huggingface
- obstore
displayName:
type: string
name:
$ref: '#/components/schemas/VariableName'
protocol:
type: string
rootPath:
type: string
storageEntries:
items:
$ref: '#/components/schemas/StorageEntry'
type: array
required:
- name
- displayName
- protocol
- rootPath
- backendType
- storageEntries
title: StorageNamespace
type: object
StorageNamespacesNotification:
description: "Available storage namespaces for storage inspector.\n\n Attributes:\n\
\ namespaces: Available storage namespaces."
properties:
namespaces:
items:
$ref: '#/components/schemas/StorageNamespace'
type: array
op:
enum:
- storage-namespaces
required:
- op
- namespaces
title: StorageNamespacesNotification
type: object
StoreConfig:
description: Configuration for a single cache store.
properties:
args:
type: object
type:
enum:
- file
- redis
- rest
- tiered
required: []
title: StoreConfig
type: object
SuccessResponse:
properties:
success:
default: true
type: boolean
required: []
title: SuccessResponse
type: object
SyncSandboxResponse:
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
reconnect:
default: false
type: boolean
restartRequired:
default: false
type: boolean
success:
type: boolean
required:
- success
title: SyncSandboxResponse
type: object
ToolDefinition:
description: Tool definition compatible with ai-sdk-ui format.
properties:
description:
type: string
mode:
items:
enum:
- agent
- ask
- code_mode
- manual
type: array
name:
type: string
parameters:
type: object
source:
enum:
- backend
- frontend
- mcp
required:
- name
- description
- parameters
- source
- mode
title: ToolDefinition
type: object
Transaction:
description: "An atomic batch of changes applied to a NotebookDocument.\n\n\
\ `source` identifies the writer (e.g. `\"frontend\"`, `\"kernel\"`).\n\
\ `version` is `None` when created and stamped by\n `NotebookDocument.apply()`."
properties:
changes:
items:
anyOf:
- $ref: '#/components/schemas/CreateCell'
- $ref: '#/components/schemas/DeleteCell'
- $ref: '#/components/schemas/MoveCell'
- $ref: '#/components/schemas/ReorderCells'
- $ref: '#/components/schemas/SetCode'
- $ref: '#/components/schemas/SetName'
- $ref: '#/components/schemas/SetConfig'
discriminator:
mapping:
create-cell: '#/components/schemas/CreateCell'
delete-cell: '#/components/schemas/DeleteCell'
move-cell: '#/components/schemas/MoveCell'
reorder-cells: '#/components/schemas/ReorderCells'
set-code: '#/components/schemas/SetCode'
set-config: '#/components/schemas/SetConfig'
set-name: '#/components/schemas/SetName'
propertyName: type
type: array
source:
enum:
- cell-manager
- code-mode
- file-watch
- frontend
- host
- kernel
version:
anyOf:
- type: integer
- type: 'null'
default: null
required:
- changes
- source
title: Transaction
type: object
TyLanguageServerConfig:
description: 'Configuration options for Ty Language Server.
ty handles completion, hover, go-to-definition, and diagnostics,
but we only use it for diagnostics.'
properties:
enabled:
type: boolean
required: []
title: TyLanguageServerConfig
type: object
UIElementId:
format: ui-element-id
type: string
UIElementMessageNotification:
description: "Sends a message to a UI element/widget.\n\n Attributes:\n \
\ ui_element: UI element identifier.\n message: Message payload\
\ as dictionary.\n buffers: Optional binary buffers for large data."
properties:
buffers:
anyOf:
- items:
$ref: '#/components/schemas/Base64String'
type: array
- type: 'null'
default: null
message:
type: object
op:
enum:
- send-ui-element-message
ui_element:
$ref: '#/components/schemas/UIElementId'
required:
- op
- ui_element
- message
title: UIElementMessageNotification
type: object
UnknownError:
properties:
error_type:
anyOf:
- type: string
- type: 'null'
default: null
msg:
type: string
type:
enum:
- unknown
required:
- type
- msg
title: UnknownError
type: object
UpdateCellConfigCommand:
description: "Update cell configuration.\n\n Updates cell-level settings\
\ like disabled state, hide code, etc.\n\n Attributes:\n configs:\
\ Cell IDs mapped to their config updates. Each config dict\n \
\ can contain partial updates."
properties:
configs:
additionalProperties:
type: object
type: object
type:
enum:
- update-cell-config
required:
- type
- configs
title: UpdateCellConfigCommand
type: object
UpdateCellOutputsRequest:
properties:
cellIdsToOutput:
additionalProperties:
items: false
maxItems: 2
minItems: 2
prefixItems:
- enum:
- application/json
- application/vnd.jupyter.widget-view+json
- application/vnd.marimo+error
- application/vnd.marimo+mimebundle
- application/vnd.marimo+traceback
- application/vnd.vega.v5+json
- application/vnd.vega.v6+json
- application/vnd.vegalite.v5+json
- application/vnd.vegalite.v6+json
- image/avif
- image/bmp
- image/gif
- image/jpeg
- image/png
- image/svg+xml
- image/tiff
- text/csv
- text/html
- text/latex
- text/markdown
- text/password
- text/plain
- video/mp4
- video/mpeg
- {}
type: array
type: object
required:
- cellIdsToOutput
title: UpdateCellOutputsRequest
type: object
UpdateManifestRequest:
properties:
contents:
type: string
fileKey:
anyOf:
- type: string
- type: 'null'
default: null
previous:
type: string
required:
- contents
- previous
title: UpdateManifestRequest
type: object
UpdateUIElementCommand:
description: "Update UI element values.\n\n Triggered when users interact\
\ with UI elements (sliders, inputs, dropdowns, etc.).\n Updates element\
\ values and re-executes dependent cells.\n\n Attributes:\n object_ids:\
\ UI elements to update.\n values: New values for the elements. Must\
\ match length of object_ids.\n request: HTTP request context if available.\n\
\ token: Unique request identifier for deduplication."
properties:
objectIds:
items:
$ref: '#/components/schemas/UIElementId'
type: array
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
token:
type: string
type:
enum:
- update-ui-element
values:
type: array
required:
- type
- objectIds
- values
title: UpdateUIElementCommand
type: object
UpdateUIElementRequest:
properties:
objectIds:
items:
$ref: '#/components/schemas/UIElementId'
type: array
request:
anyOf:
- $ref: '#/components/schemas/HTTPRequest'
- type: 'null'
default: null
token:
type: string
values:
type: array
required:
- objectIds
- values
title: UpdateUIElementRequest
type: object
UpdateUIElementValuesRequest:
properties:
objectIds:
items:
$ref: '#/components/schemas/UIElementId'
type: array
values:
type: array
required:
- objectIds
- values
title: UpdateUIElementValuesRequest
type: object
UpdateUserConfigRequest:
properties:
config:
$ref: '#/components/schemas/MarimoConfig'
required:
- config
title: UpdateUserConfigRequest
type: object
ValidateSQLCommand:
description: "Validate an SQL query.\n\n Checks if an SQL query is valid\
\ by parsing against a dialect (no DB connection)\n or validating against\
\ an actual database.\n\n Attributes:\n request_id: Unique identifier\
\ for this request.\n query: SQL query to validate.\n only_parse:\
\ If True, only parse using dialect. If False, validate against DB.\n \
\ engine: SQL engine (required if only_parse is False).\n dialect:\
\ SQL dialect for parsing (required if only_parse is True)."
properties:
dialect:
anyOf:
- type: string
- type: 'null'
default: null
engine:
anyOf:
- type: string
- type: 'null'
default: null
onlyParse:
type: boolean
query:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
type:
enum:
- validate-sql
required:
- type
- requestId
- query
- onlyParse
title: ValidateSQLCommand
type: object
ValidateSQLRequest:
properties:
dialect:
anyOf:
- type: string
- type: 'null'
default: null
engine:
anyOf:
- type: string
- type: 'null'
default: null
onlyParse:
type: boolean
query:
type: string
requestId:
$ref: '#/components/schemas/RequestId'
required:
- requestId
- query
- onlyParse
title: ValidateSQLRequest
type: object
ValidateSQLResultNotification:
description: "SQL query validation result.\n\n Attributes:\n request_id:\
\ Request ID this responds to.\n parse_result: SQL parsing result.\n\
\ validate_result: Catalog validation result.\n error: Error\
\ message if failed."
properties:
error:
anyOf:
- type: string
- type: 'null'
default: null
op:
enum:
- validate-sql-result
parse_result:
anyOf:
- $ref: '#/components/schemas/SqlParseResult'
- type: 'null'
default: null
request_id:
$ref: '#/components/schemas/RequestId'
validate_result:
anyOf:
- $ref: '#/components/schemas/SqlCatalogCheckResult'
- type: 'null'
default: null
required:
- op
- request_id
title: ValidateSQLResultNotification
type: object
VariableContext:
properties:
name:
type: string
previewValue: {}
valueType:
type: string
required:
- name
- valueType
- previewValue
title: VariableContext
type: object
VariableDeclarationNotification:
description: "Variable declaration and usage for dataflow graph.\n\n Attributes:\n\
\ name: Variable name.\n declared_by: Cell IDs that define this\
\ variable.\n used_by: Cell IDs that use this variable."
properties:
declared_by:
items:
$ref: '#/components/schemas/CellId'
type: array
name:
$ref: '#/components/schemas/VariableName'
used_by:
items:
$ref: '#/components/schemas/CellId'
type: array
required:
- name
- declared_by
- used_by
title: VariableDeclarationNotification
type: object
VariableName:
format: variable-name
type: string
VariableRemoval:
description: A binding removed from the runtime's namespace.
properties:
execution_id:
type: string
name:
type: string
required:
- name
- execution_id
title: VariableRemoval
type: object
VariableValue:
description: "Variable value and type for variables panel.\n\n Attributes:\n\
\ name: Variable name.\n value: String representation of value.\n\
\ datatype: Data type as string."
properties:
datatype:
anyOf:
- type: string
- type: 'null'
execution_id:
anyOf:
- type: string
- type: 'null'
default: null
name:
type: string
revision:
anyOf:
- $ref: '#/components/schemas/Revision'
- type: 'null'
default: null
value:
anyOf:
- type: string
- type: 'null'
required:
- name
- value
- datatype
title: VariableValue
type: object
VariableValuesNotification:
description: "Current variable values.\n\n Attributes:\n variables:\
\ Variables with current values and types.\n removed: Bindings that\
\ no longer exist, identified by their producer."
properties:
op:
enum:
- variable-values
removed:
default: []
items:
$ref: '#/components/schemas/VariableRemoval'
type: array
variables:
items:
$ref: '#/components/schemas/VariableValue'
type: array
required:
- op
- variables
title: VariableValuesNotification
type: object
VariablesNotification:
description: "Variable dataflow graph.\n\n Attributes:\n variables:\
\ Variable declarations and usage."
properties:
op:
enum:
- variables
variables:
items:
$ref: '#/components/schemas/VariableDeclarationNotification'
type: array
required:
- op
- variables
title: VariablesNotification
type: object
VenvConfig:
description: "Configuration for an external Python environment in edit mode.\n\
\n Launches the notebook kernel in an existing virtualenv. Applies to\n\
\ single notebooks and directories when editing without `--sandbox`.\n\n\
\ **Keys.**\n\n - `path`: path to a virtualenv directory (absolute or\
\ relative to\n pyproject.toml)\n - `writable`: if true, marimo will\
\ manage script metadata (inline\n dependencies). Defaults to false."
properties:
path:
type: string
writable:
type: boolean
required: []
title: VenvConfig
type: object
WidgetModelId:
format: widget-model-id
type: string
WorkspaceFilesRequest:
properties:
includeMarkdown:
default: false
type: boolean
required: []
title: WorkspaceFilesRequest
type: object
WorkspaceFilesResponse:
properties:
fileCount:
default: 0
type: integer
files:
items:
$ref: '#/components/schemas/FileInfo'
type: array
hasMore:
default: false
type: boolean
root:
type: string
required:
- root
- files
title: WorkspaceFilesResponse
type: object
_AppConfig:
description: "Program-specific configuration.\n\n Configuration for frontends\
\ or runtimes that is specific to\n a single marimo program."
properties:
app_title:
anyOf:
- type: string
- type: 'null'
default: null
auto_download:
items:
enum:
- html
- ipynb
- markdown
type: array
css_file:
anyOf:
- type: string
- type: 'null'
default: null
html_head_file:
anyOf:
- type: string
- type: 'null'
default: null
layout_file:
anyOf:
- type: string
- type: 'null'
default: null
sql_output:
default: auto
enum:
- auto
- lazy-polars
- native
- pandas
- polars
width:
default: compact
enum:
- columns
- compact
- full
- medium
- normal
required: []
title: _AppConfig
type: object
info:
title: marimo API
openapi: 3.1.0
paths:
/@file/{filename_and_length}:
get:
parameters:
- description: The filename and byte length of the virtual file
in: path
name: filename_and_length
required: true
schema:
type: string
responses:
200:
content:
application/octet-stream:
schema:
type: string
description: Get a virtual file
404:
description: Invalid byte length in virtual file request
/api/ai/chat:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatRequest'
description: The request body for AI chat
required: true
/api/ai/completion:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AiCompletionRequest'
description: The request body for AI completion
required: true
responses:
200:
content:
application/json:
schema:
additionalProperties: true
type: object
description: Get AI completion for a prompt
/api/ai/inline_completion:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AiInlineCompletionRequest'
description: The request body for AI inline completion
required: true
responses:
200:
content:
text/plain:
schema:
type: string
description: Get AI inline completion for code
/api/ai/invoke_tool:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeAiToolRequest'
description: The request body for tool invocation
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeAiToolResponse'
description: Tool invocation result
/api/ai/mcp/refresh:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/MCPRefreshResponse'
description: Refresh MCP server configuration
/api/ai/mcp/status:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/MCPStatusResponse'
description: Get MCP server status
/api/cache/clear:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClearCacheRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Clear all caches
/api/cache/info:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetCacheInfoRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Get cache statistics
/api/datasources/discover:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DiscoverDataSourcesRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Discover datasource connections
/api/datasources/preview_column:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewDatasetColumnRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Preview a column in a dataset
/api/datasources/preview_datasource_connection:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListDataSourceConnectionRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Broadcasts a datasource connection
/api/datasources/preview_sql_schema_list:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListSQLSchemasRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Preview a list of schemas in an SQL database
/api/datasources/preview_sql_table:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewSQLTableRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Preview a SQL table
/api/datasources/preview_sql_table_list:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListSQLTablesRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Preview a list of tables in an SQL schema
/api/documentation/snippets:
get:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/Snippets'
description: Load the snippets for the documentation page
/api/environment:
get:
responses:
200:
content:
application/json:
schema:
properties:
Binaries:
additionalProperties:
type: string
type: object
Dependencies:
additionalProperties:
type: string
type: object
Experimental Flags:
additionalProperties: {}
type: object
Locale:
type: string
OS:
type: string
OS Version:
type: string
Optional Dependencies:
additionalProperties:
type: string
type: object
Processor:
type: string
Python Version:
type: string
editable:
type: boolean
location:
type: string
marimo:
type: string
required:
- marimo
- editable
- location
- OS
- OS Version
- Processor
- Python Version
- Locale
- Binaries
- Dependencies
- Optional Dependencies
- Experimental Flags
type: object
description: Environment information for issue reporting
/api/export/auto_export/html:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsHTMLRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Export the notebook as HTML
400:
description: File must be saved before downloading
/api/export/auto_export/ipynb:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoExportAsIPYNBRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Export the notebook as IPYNB
400:
description: File must be saved before downloading
/api/export/auto_export/markdown:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoExportAsMarkdownRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Export the notebook as a markdown
400:
description: File must be saved before downloading
/api/export/availability:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAvailabilityResponse'
description: Readiness for server-backed exports
/api/export/html:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsHTMLRequest'
responses:
200:
content:
text/html:
schema:
type: string
description: Export the notebook as HTML
400:
description: File must be saved before downloading
/api/export/ipynb:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsIPYNBRequest'
responses:
200:
content:
text/plain:
schema:
type: string
description: Export the notebook as IPYNB
400:
description: File must be saved before downloading
/api/export/markdown:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsMarkdownRequest'
responses:
200:
content:
text/plain:
schema:
type: string
description: Export the notebook as a markdown
400:
description: File must be saved before downloading
/api/export/pdf:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsPDFRequest'
responses:
200:
content:
application/pdf:
schema:
format: binary
type: string
description: Export the notebook as a PDF
400:
description: File must be saved before downloading
500:
description: Export failed or dependencies missing
/api/export/requirements/install:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstallExportRequirementsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAvailabilityResponse'
description: Updated readiness for server-backed exports
/api/export/script:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExportAsScriptRequest'
responses:
200:
content:
text/plain:
schema:
type: string
description: Export the notebook as a script
400:
description: Invalid export request
/api/export/update_cell_outputs:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCellOutputsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Update the cell outputs
400:
description: File must be saved before downloading
/api/files/copy:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileCopyRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileCopyResponse'
description: Copy a file or directory
/api/files/create:
post:
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileCreateMultipartRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileCreateResponse'
description: Create a new file or directory
/api/files/delete:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileDeleteRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileDeleteResponse'
description: Delete a file or directory
/api/files/download:
get:
parameters:
- description: Path of the file to download
in: query
name: path
required: true
schema:
type: string
responses:
200:
content:
application/octet-stream:
schema:
format: binary
type: string
description: Stream the file as an attachment
400:
description: Path is missing or is a directory
403:
description: File downloads are disabled
404:
description: File not found
/api/files/file_details:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetailsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetailsResponse'
description: Get details of a specific file or directory
/api/files/list_files:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileListRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileListResponse'
description: List files and directories in a given path
/api/files/move:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileMoveRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileMoveResponse'
description: Move a file or directory
/api/files/open:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileOpenRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
description: Open a file in the system editor
/api/files/roots:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileRootsResponse'
description: List roots shown in the file browser
/api/files/search:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileSearchRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileSearchResponse'
description: Search for files and directories matching a query
/api/files/update:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileUpdateRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FileUpdateResponse'
description: Update a file or directory
/api/home/recent_files:
post:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/RecentFilesResponse'
description: Get the recent files
/api/home/running_notebooks:
post:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/RunningNotebooksResponse'
description: Get the running files
/api/home/shutdown_session:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShutdownSessionRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/RunningNotebooksResponse'
description: Shutdown the current session
/api/home/tutorial/open:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OpenTutorialRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/MarimoFile'
description: Open a new tutorial
/api/home/workspace_files:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceFilesRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceFilesResponse'
description: Get the files in the workspace
/api/kernel/code_autocomplete:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CodeCompletionRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Complete a code fragment
/api/kernel/copy:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CopyNotebookRequest'
responses:
200:
content:
text/plain:
schema:
type: string
description: Copy notebook
/api/kernel/focus_cell:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FocusCellRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Focus a cell in kiosk-mode consumers
/api/kernel/format:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FormatCellsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/FormatResponse'
description: Format code
/api/kernel/function_call:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeFunctionRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Invoke an RPC
/api/kernel/install_missing_packages:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstallPackagesRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Install missing packages
/api/kernel/instantiate:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstantiateNotebookRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Instantiate a component. Only allowed in edit mode; in run
mode, instantiation happens server-side automatically.
/api/kernel/interrupt:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Interrupt the kernel's execution
/api/kernel/pdb/breakpoints:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetBreakpointsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Set the live debugger's breakpoints for the session.
/api/kernel/pdb/pm:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DebugCellRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Run a post mortem on the most recent failed cell.
/api/kernel/read_code:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/ReadCodeResponse'
description: Read the code from the server
400:
description: File must be saved before downloading
403:
description: Code is not available in run mode
/api/kernel/rename:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RenameNotebookRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Rename the current app
/api/kernel/restart_session:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Restart the current session without affecting other sessions.
/api/kernel/run:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteCellsRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Run a cell. Updates cell code in the kernel if needed; registers
new cells for unseen cell IDs. Only allowed in edit mode.
/api/kernel/save_app_config:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SaveAppConfigurationRequest'
responses:
200:
content:
text/plain:
schema:
type: string
description: Save the app configuration
/api/kernel/save_layout:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SaveLayoutRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Write the notebook's layout file and point its app config at
it
/api/kernel/save_user_config:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SaveUserConfigurationRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Update the user config on disk and in the kernel. Only allowed
in edit mode.
/api/kernel/scratchpad/run:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteScratchpadRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Run the scratchpad
/api/kernel/set_model_value:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModelRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Set model value
/api/kernel/set_ui_element_value:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUIElementValuesRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Set UI element values
/api/kernel/shutdown:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: false
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Shutdown the kernel
/api/kernel/status:
get:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/KernelStatusResponse'
description: Report whether the kernel is currently executing. `running`
means at least one cell is queued or running; `idle` means the kernel
is alive but not executing; `stopped` means the kernel process is not
running.
/api/kernel/stdin:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StdinRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Send input to the stdin stream
/api/kernel/takeover:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
responses:
200:
content:
application/json:
schema:
properties:
status:
type: string
type: object
description: Successfully closed existing sessions
/api/lsp/health:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/LspHealthResponse'
description: Get health status of all LSP servers
/api/lsp/restart:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LspRestartRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/LspRestartResponse'
description: Restart LSP servers
/api/packages/add:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddPackageRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/PackageOperationResponse'
description: Install package
/api/packages/list:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/ListPackagesResponse'
description: List installed packages
/api/packages/manifest:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateManifestRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxResponse'
description: Save notebook metadata without changing its cells
/api/packages/remove:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RemovePackageRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/PackageOperationResponse'
description: Uninstall package
/api/packages/sandbox:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxResponse'
description: Sandbox manifest, available before kernel startup
/api/packages/sync:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SyncSandboxResponse'
description: Apply the saved manifest, or reconnect to retry startup
/api/packages/tree:
get:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/DependencyTreeResponse'
description: List dependency tree
/api/secrets/create:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSecretRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
description: Create a secret
/api/secrets/delete:
post:
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
description: Delete a secret
/api/secrets/keys:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListSecretKeysRequest'
required: true
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/ListSecretKeysResponse'
description: List all secret keys
/api/sql/validate:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateSQLRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Validate an SQL query
/api/status:
get:
responses:
200:
content:
application/json:
schema:
properties:
filenames:
items:
type: string
type: array
lsp_running:
type: boolean
mode:
type: string
node_version:
type: string
requirements:
items:
type: string
type: array
sessions:
type: integer
status:
type: string
version:
type: string
type: object
description: Get the status of the application
/api/status/connections:
get:
responses:
200:
content:
application/json:
schema:
properties:
active:
type: integer
type: object
description: Get the number of active websocket connections
/api/storage/download:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorageDownloadRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Download a storage entry
/api/storage/list_entries:
post:
parameters:
- in: header
name: Marimo-Session-Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorageListEntriesRequest'
responses:
200:
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: List storage entries at a prefix
/api/usage:
get:
responses:
200:
content:
application/json:
schema:
properties:
cpu:
properties:
percent:
type: number
required:
- percent
type: object
gpu:
items:
properties:
index:
type: integer
memory:
properties:
free:
type: integer
percent:
type: number
total:
type: integer
used:
type: integer
required:
- total
- used
- free
- percent
type: object
name:
type: string
required:
- index
- memory
- name
type: object
type: array
kernel:
properties:
memory:
type: integer
type: object
memory:
properties:
available:
type: integer
free:
type: integer
has_cgroup_mem_limit:
type: boolean
percent:
type: number
total:
type: integer
used:
type: integer
required:
- total
- available
- percent
- used
- free
- has_cgroup_mem_limit
type: object
server:
properties:
memory:
type: integer
required:
- memory
type: object
required:
- memory
- cpu
type: object
description: Get the current memory and CPU usage of the application
/api/version:
get:
responses:
200:
content:
text/plain:
schema:
type: string
description: Get the version of the application
/auth/login:
post:
requestBody:
content:
application/x-www-form-urlencoded:
schema:
properties:
password:
description: Access token or password
type: string
type: object
responses:
200:
content:
text/html:
schema:
type: string
description: Login page
302:
description: Redirect to the next URL
headers:
Location:
schema:
type: string
summary: Submit login form
tags:
- auth
/auth/token:
get:
responses:
200:
content:
application/json:
schema:
properties:
token:
nullable: true
type: string
type: object
description: The auth token (null if auth is disabled)
summary: Get the auth token for the current session
tags:
- auth