Skip to content

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.

93.9 KB
Raw Blame
openapi: 3.1.0
info:
  title: marimo host protocol
  version: 1.0.0
  description: |
    The contract a marimo host serves so that other programs on the same
    machine can find it, see what it has, and work with its notebooks. A
    host is a program that runs marimo notebooks, such as the marimo CLI
    or the VS Code extension. A client is a program that talks to a host
    from the outside, such as Pair.

    A host writes a small file, the host record, that says where its API
    is and how to authenticate. A client reads that file, opens the host's
    event stream to learn what it has, and calls the operations the host
    lists. There are two streams: `/events` carries the catalog, and
    `/notebooks/{notebook_id}/events` carries one notebook: its cells and
    document, its runtime, and the runs of code against it. Clients ignore
    fields, operation names, event
    names, and problem types they do not recognize. A change that would
    break an existing client requires a new record version and a new base
    path.
security:
  - hostToken: []
paths:
  /events:
    get:
      operationId: events
      summary: Read the host's catalog as a stream
      description: |
        Sends everything the host has, then every change as it happens.
        The response is a stream of server-sent events, so it stays open
        and the host appends one event at a time. The catalog is the host
        object, its projects, notebooks, runtimes, and attachments.

        A new connection starts with one event per object the host knows
        about, parents before children, followed by a `ready` event.
        Snapshot events have no `id`; `ready` and live events have an `id`
        line. The most recent `id` a client has seen is its position in
        the stream. When a connection drops, the client reconnects and
        sends that position in the `Last-Event-ID` header. If the host
        still has the events after that point, it sends them with their
        original ids and timestamps, even before the new `ready`, and then
        `ready`. If it does not, or the cursor predates a loss of host
        state, it sends `reset`, and the client discards what it holds and
        receives the full state again. A client also
        discards an incomplete snapshot before reconnecting without a
        cursor. On `reset` it clears its cursor until the next `ready`.

        `types` limits the stream to some kinds of object without changing
        ids or positions. It also filters the host object; `ready` and
        `reset` are always sent. Keep the same filter when resuming a
        cursor. The host writes a `: ping` comment every fifteen seconds
        when nothing else is happening. A client that hears nothing for 45
        seconds treats the connection as lost and reconnects.
      parameters:
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/LastEventId'
      responses:
        '200':
          description: The catalog, then changes, as server-sent events.
          content:
            text/event-stream:
              schema:
                description: |
                  One event. `data` holds JSON, and the event name says
                  which shape: a HostMessage, ProjectMessage,
                  NotebookMessage, RuntimeMessage, or AttachmentMessage
                  for an event named after that object; a RemovedMessage
                  for an event ending in `.removed`; and an empty object
                  for `ready` and `reset`.
                type: object
                required: [event, data]
                properties:
                  id:
                    type: string
                    description: The resume cursor. Omitted on snapshot and reset events.
                  event:
                    type: string
                    description: The object kind, a kind ending in `.removed`, `ready`, or `reset`. Clients ignore unknown names but retain their cursor.
                  data:
                    type: string
                    description: The message as JSON. Unknown event names do not require decoding this field.
              x-effect-stream:
                encoding: sse
                errorSchema: { $ref: '#/components/schemas/Problem' }
                failureEvent: effect/httpapi/stream/failure
              example: "event: host\ndata: {\"host\":{\"operations\":[\"runtime.start\"]}}\n\nid: 41\nevent: ready\ndata: {}\n\n"
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '500': { $ref: '#/components/responses/Internal' }
  /notebooks:
    post:
      operationId: notebook.create
      summary: Create a notebook
      description: |
        Adds an empty notebook to the project. The request carries the
        notebook's own fields, and the host fills in what it owns. In a
        project with a `root`, `path` is required and `name` defaults to
        the filename; if a file already exists at `path`, the host
        answers `conflict` and leaves it alone. In a project without a
        root, `name` is required, the host chooses storage, and `path` is
        null. A request missing the required field is `invalid-request`.
        The new notebook appears on the catalog stream with this
        request's key.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateNotebookRequest' }
      responses:
        '201':
          description: The notebook was created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notebook' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}:
    patch:
      operationId: notebook.update
      summary: Rename or move a notebook
      description: |
        Changes `path`, `name`, or both. A new `path` moves the file
        under the same project root, and an attached runtime follows it.
        A new `name` changes the label shown to people. What the file
        contains is content, which this protocol does not write. If a
        file already exists at `path`, the host answers `conflict`.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateNotebookRequest' }
      responses:
        '200':
          description: The notebook as it now is.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notebook' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
    delete:
      operationId: notebook.delete
      summary: Delete a notebook
      description: |
        Deletes the file. While the notebook has a runtime, the host
        answers `conflict` instead.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: The notebook was deleted.
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/events:
    get:
      operationId: notebook.events
      summary: Follow one notebook as a stream
      description: |
        Sends the notebook, its cells and document, its runtime, its
        attachments, its runs, their executions, and their items, then
        every change as it happens. The
        stream follows the same rules as `/events`: a snapshot that ends
        in `ready`, ids as positions, `Last-Event-ID` to resume, `reset`
        when the host cannot, a `: ping` comment every fifteen seconds,
        and `types` to limit the kinds sent. The optional `run_id` query
        narrows the stream to one run. A cursor belongs to the stream it
        came from.

        Opening this stream attaches the client to the notebook. An
        attachment appears on both streams while the connection is open
        and is removed when it closes. Every opening, including a reconnect,
        creates a separate attachment. The optional
        `Marimo-Attachment-Identity` header supplies its `identity` so
        consumers can group connections from the same client. A shared
        identity does not merge attachments or extend their lifetimes.
        The snapshot includes every run that is not yet completed, with
        its executions and items, plus
        any completed results the host retains. Result retention is
        independent of replay history. Removed objects are absent from
        snapshots; a resumable stream carries their removal events.

        The stream may also carry `custom` events: namespaced JSON payloads
        that describe occurrences rather than object state. These have
        cursors and timestamps and participate in replay, but never appear
        in snapshots. A reset cannot recover custom events whose history
        has expired. `types=custom` selects them. They do not belong to a
        run and are excluded by `run_id`.

        The opening phase is one consistent cut of the notebook, taken
        under the lock that changes to the document take, so reading to
        `ready` and closing is a snapshot, and `types=cell,document` is a
        snapshot of the document alone. Cells arrive before the document
        that orders them, in the opening phase and after every change, so
        a client never holds a document whose `order` names a cell it has
        not received. The effects of one change to the document arrive
        together, with no other event between them.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/RunFilter'
        - $ref: '#/components/parameters/LastEventId'
        - $ref: '#/components/parameters/AttachmentIdentity'
        - $ref: '#/components/parameters/AttachmentKind'
        - $ref: '#/components/parameters/AttachmentName'
      responses:
        '200':
          description: The notebook, then changes, as server-sent events.
          content:
            text/event-stream:
              schema:
                description: |
                  One event. `data` holds JSON, and the event name says
                  which shape: a NotebookMessage, DocumentMessage,
                  CellMessage, RuntimeMessage, AttachmentMessage,
                  RunMessage, ExecutionMessage, ConsoleMessage,
                  DisplayMessage, or VariableMessage for an event named
                  after that kind; a CustomMessage for `custom`; a RemovedMessage
                  for an event ending in `.removed`; and an empty object
                  for `ready` and `reset`.
                type: object
                required: [event, data]
                properties:
                  id:
                    type: string
                    description: The resume cursor. Omitted on snapshot and reset events.
                  event:
                    type: string
                    description: The kind, a kind ending in `.removed`, `ready`, or `reset`. Clients ignore unknown names but retain their cursor.
                  data:
                    type: string
                    description: The message as JSON. Unknown event names do not require decoding this field.
              x-effect-stream:
                encoding: sse
                errorSchema: { $ref: '#/components/schemas/Problem' }
                failureEvent: effect/httpapi/stream/failure
              example: "event: notebook\ndata: {\"notebook\":{\"id\":\"n1\",\"project_id\":\"p1\",\"path\":\"forecasts.py\",\"name\":\"forecasts\",\"operations\":[],\"updated_at\":null}}\n\nid: 41\nevent: ready\ndata: {}\n\n"
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '500': { $ref: '#/components/responses/Internal' }
  /notebooks/{notebook_id}/edits:
    post:
      operationId: notebook.edit
      summary: Change parts of the document
      description: |
        Applies an ordered list of changes to the document as one unit.
        Each change says what it replaces and carries the etag that state
        had when the client read it, so two writers never silently
        overwrite each other. Every etag is compared with the document as
        it was when the request arrived, so one request can create a cell
        and then place it with the order etag the client read. Cells and
        the order each have their own etag, so writers touching different
        parts never conflict. An etag of `*` skips the check. A `put_cell`
        with a null etag creates the cell, after or before an existing cell
        or at the end; placement has no precondition, so two clients
        inserting at once both succeed.

        If any precondition is stale, nothing is applied and the host
        answers `conflict` with `edit` naming the first stale change and
        carrying the object as it now is. A change that could not apply to
        any state, such as an order that leaves out a cell or names one
        twice, is `invalid-request`.

        On success the document has changed, and every attachment sees
        the effects on the notebook's stream with this request's key: the
        cells that changed, `cell.removed` for each deleted cell, and then
        the document, with nothing in between. The response carries the new
        etags, as of this edit or a later revision, so a client keeps editing without reading again. A
        change that changes nothing keeps its etags and sends no events.
        Whether the result has reached the store shows in the document's
        `saved_etag`.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EditRequest' }
      responses:
        '200':
          description: The changes were applied.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EditResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/save:
    post:
      operationId: notebook.save
      summary: Write the document to the host's store
      description: |
        Writes the document as currently applied, after which `saved_etag`
        equals `etag`. There is no body to send, since the host already
        holds the state. A host that persists every change as it applies
        it need not offer this operation. A client shows a save control
        when the notebook lists it, and reads whether anything is unsaved
        from the two etags either way.

        The response is an edit response, because a host may rewrite code
        as it saves, for example to format it. Such changes reach the
        stream like any other and the response carries the new etags.
        `If-Match` makes the document etag the client last read a
        precondition; the host answers `conflict` when the document has
        moved on. If the store has changed since the host last read or
        wrote it, the host answers `decision-required`, offering to
        overwrite the store or to reload from it, and the client repeats
        the request with its decision and a new key.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SaveRequest' }
      responses:
        '200':
          description: The document is in the store.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EditResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/open:
    post:
      operationId: notebook.open
      summary: Show a notebook in the host's own interface
      description: |
        Opens the notebook where the host normally shows notebooks, such
        as a browser tab or an editor, and returns the URL it used.
        Opening may start a runtime. The URL never contains the host's
        token, and a client opens it exactly as given. If the notebook
        cannot be shown, for example because its file is gone, the host
        answers `conflict`.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: The notebook is being shown.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OpenNotebookResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/runtime:
    put:
      operationId: runtime.start
      summary: Start the notebook's runtime, or find the one it has
      description: |
        Makes sure the notebook has a running runtime. If it has none, the
        host starts one and answers `202` with the runtime `starting`. The
        client then follows `runtime` events for that runtime, on either
        stream, until its status is `running` or `failed`. If the notebook
        already has a runtime, the host answers `200` with it and starts
        nothing.

        Sometimes the host needs a choice the client did not make, such as
        which environment the kernel should run in. It then answers `409`
        with a problem of type `decision-required` that lists the options,
        and the client repeats the request with a new `Idempotency-Key`
        and `decisions` filled in. A client that already knows its choice
        can include `decisions` the first time.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StartRuntimeRequest' }
      responses:
        '200':
          description: The notebook already has a runtime.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Runtime' }
        '202':
          description: A runtime is starting. Follow it on a stream.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Runtime' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
    delete:
      operationId: runtime.stop
      summary: Stop the notebook's runtime
      description: |
        Ends the runtime for everyone attached to the notebook. A runtime
        that is still starting is cancelled; a running kernel is shut
        down. Running executions end `interrupted`. Retained results stay
        and are no longer live. The notebook and its attachments stay,
        but Python state is lost. The client follows the
        runtime on a stream until `runtime.removed`. If the notebook has
        no runtime, the host answers `no-runtime`.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: The runtime is shutting down.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Runtime' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/runtime/restart:
    post:
      operationId: runtime.restart
      summary: Restart the notebook's kernel
      description: |
        Stops the runtime and starts a new one with a new id. The stream
        shows the old runtime `terminating`, then `runtime.removed`, then
        the new runtime `starting`, so a notebook never has two runtimes
        at once. Running executions end `interrupted`. Retained results
        stay and are no longer live. The response carries the replacement
        runtime in its `starting` state. The client follows that id until
        it is `running` or has `failed`. If the notebook has no runtime,
        the host answers `no-runtime`.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: The replacement runtime is starting. Follow its id on a stream.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Runtime' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/runtime/runs:
    post:
      operationId: runtime.run
      summary: Run code or cells against the notebook's runtime
      description: |
        Runs `code` in a copy of the notebook runtime's namespace, or runs
        `cells` of the document. Scratch code stays out of the graph and
        its execution carries the submitted code. The runtime's execution
        configuration determines whether dependent cells run too. Each cell
        gets an execution with its `cell_id` and no code. The host assigns a run
        id independent of the request's `Idempotency-Key` and answers `202`
        with the run `queued` or `running`. The rest arrives on the notebook's
        stream with this request's key: executions as they start, console
        and display items, the variables each cell execution bound, and a
        final execution whose `outcome` is
        `value`, `error`, or `interrupted`, and a final `run` whose
        status is `completed`. A client that wants to see all of it opens
        the notebook's stream before sending the request.

        A cell in `cells` that the document does not have, or whose
        `code_hash` is not the one the request carries, is a `conflict`
        whose `edit` names the cell and its index in `cells`, and nothing
        runs. A client that read the cells from the stream sends their
        `code_hash` so that an edit it did not see is a conflict rather
        than a run of other code.

        One run is in progress at a time. The host answers `no-runtime`
        when the notebook has no runtime and `conflict` while another run
        is in progress. Within the host's retry window, repeating the
        request returns its latest run record without executing again,
        even if its outputs have expired. A call to `input()` gets end of
        file rather than blocking.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RunRequest' }
      responses:
        '202':
          description: The run was accepted. Follow it on the notebook's stream.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Run' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
  /notebooks/{notebook_id}/runtime/runs/{run_id}:
    delete:
      operationId: runtime.interrupt
      summary: Interrupt a run
      description: |
        Stops a run that is in progress. The notebook's stream then
        carries its executions with the outcome `interrupted` and the
        run with status `completed` and outcome `interrupted` once the
        interruption has taken effect. Queued executions end `interrupted` and
        the running one is interrupted. A host may answer `conflict`
        for a run that has not started. Once the run is completed, the host
        answers `conflict`. A host that lists `runtime.run` supports this route.
      parameters:
        - $ref: '#/components/parameters/NotebookId'
        - $ref: '#/components/parameters/RunId'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: The run is being interrupted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Run' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '405': { $ref: '#/components/responses/MethodNotAllowed' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }
        '501': { $ref: '#/components/responses/UnsupportedOperation' }
components:
  securitySchemes:
    hostToken:
      type: http
      scheme: bearer
      description: |
        The `token` from a host record, sent as `Authorization: Bearer
        <token>` on every request. Hosts accept the token only in that
        header, never in a cookie or a query parameter, and send no CORS
        headers. Hosts answer only requests that arrive over the machine's
        own loopback interface, and clients never follow redirects, so the
        token never leaves the machine.
  parameters:
    AttachmentIdentity:
      name: Marimo-Attachment-Identity
      in: header
      required: false
      description: |
        An opaque client identity, copied to the attachment's `identity`.
        Clients can reuse it across streams and reconnects so consumers
        can group their attachments within a host. It is descriptive data,
        not an authentication credential or an idempotency key. Every
        stream still creates its own attachment. Invalid values receive
        a 400 `invalid-request` response.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: '^[!-~]+$'
    AttachmentKind:
      name: Marimo-Attachment-Kind
      in: header
      required: false
      description: |
        What kind of client is attached, such as `browser`, `editor`, or
        `agent`. Copied to the attachment's `kind`; omitted means `client`.
        Hosts accept kinds they do not recognize. Values must contain one
        or more lowercase ASCII letters, digits, or hyphens; invalid values
        receive a 400 `invalid-request` response.
      schema:
        type: string
        pattern: '^[a-z0-9-]+$'
        default: client
    AttachmentName:
      name: Marimo-Attachment-Name
      in: header
      required: false
      description: |
        A human-readable label copied to the attachment's `name`, such as
        `Notebook CLI`. Omitted or empty means the attachment's name is
        null. The value must be at most 256 characters; longer values
        receive a 400 `invalid-request` response.
      schema:
        type: string
        maxLength: 256
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        A key the client makes up for this request, such as a UUID. It
        does two jobs. If the client sends the same request again, for
        example after a timeout, the host returns the original response
        instead of doing the work twice. And the host puts the key on
        every event about the object the request changed, as
        `request_id`, until that object reaches a final status, so the
        client can tell which changes it caused. Sending the same key with
        a different request is a `conflict`. Keys are scoped to the host,
        across all mutation routes, for a host-documented retry window
        independent of result and replay retention. Repeating a run request
        returns its latest run record, even if its outputs have expired.
        Outside that window or after loss of host state, the key may execute
        again. Error responses do not reserve a key. Clients use fresh keys
        for new work and decision retries.
      schema: { type: string }
    NotebookId:
      name: notebook_id
      in: path
      required: true
      description: The notebook's id.
      schema: { $ref: '#/components/schemas/NotebookId' }
    RunId:
      name: run_id
      in: path
      required: true
      description: The run's id.
      schema: { $ref: '#/components/schemas/RunId' }
    RunFilter:
      name: run_id
      in: query
      required: false
      description: Narrows the notebook stream to one run.
      schema: { $ref: '#/components/schemas/RunId' }
    Types:
      name: types
      in: query
      required: false
      description: Which kinds to send, as a comma-separated list of kind names such as `runtime,project`. Omit it to receive every kind the stream carries.
      schema: { type: string }
    LastEventId:
      name: Last-Event-ID
      in: header
      required: false
      description: The `id` of the last event the client received, when reconnecting.
      schema: { type: string }
    IfMatch:
      name: If-Match
      in: header
      required: false
      description: The document etag the client last read, as a precondition. The host answers `conflict` when the document's etag differs.
      schema: { type: string }
  responses:
    InvalidRequest:
      description: The body or parameters are malformed.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Unauthorized:
      description: The token is missing or wrong.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Forbidden:
      description: The request did not come from this machine.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    NotFound:
      description: There is no such object or route.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    MethodNotAllowed:
      description: The route exists but not for this method. `Allow` lists the methods it accepts.
      headers:
        Allow:
          schema: { type: string }
          description: The methods this route accepts, comma separated.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    NotAcceptable:
      description: No representation the host produces satisfies `Accept`.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Conflict:
      description: The request conflicts with the current state (`conflict`), needs a runtime the notebook does not have (`no-runtime`), or needs a decision first (`decision-required`).
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    UnsupportedOperation:
      description: The host does not offer this operation. Its `operations` list says which it does.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Internal:
      description: The host failed.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
  schemas:
    ProjectId:
      type: string
      minLength: 1
      description: Identifies a project. Unique within the host and unchanged while the project exists.
    NotebookId:
      type: string
      minLength: 1
      description: Identifies a notebook. Unique within the host and unchanged while the notebook exists.
    RuntimeId:
      type: string
      minLength: 1
      description: Identifies a runtime. Unique within the host; every start and restart creates a new id.
    AttachmentId:
      type: string
      minLength: 1
      description: Identifies an attachment. Unique within the host.
    RunId:
      type: string
      minLength: 1
      description: Identifies a run independently of the request's `Idempotency-Key`. Events carry the key in `request_id`.
    ExecutionId:
      type: string
      minLength: 1
      description: Identifies an execution. Unique within the host.
    ItemId:
      type: string
      minLength: 1
      description: Identifies a console, display, or variable item. Unique within the host; sending an item again with the same id replaces it.
    CellId:
      type: string
      minLength: 1
      description: Identifies a cell within its notebook. Stable while the host serves the notebook; whether it survives a reload of the store depends on the format. `setup` is the setup cell.
    HostRecord:
      type: object
      description: |
        A host record is the file a host writes so that clients can find
        it. A host writes `<marimo-state-dir>/hosts-v1/<id>.json` once its API
        is serving at `url`, where `<id>` is an identifier the host makes
        up each time it starts. The record does not change while the host
        runs, and the host removes it when it stops.

        A client reads `version` before anything else and skips any record
        it cannot parse or whose version it does not support. It also
        checks that the file and its directory belong to the current user
        and cannot be read by others, and that `url` points at this
        machine.
      required: [version, process, name, url, token]
      properties:
        version:
          type: integer
          enum: [1]
          description: The version of this record's format. This document describes version 1.
        process: { $ref: '#/components/schemas/Process' }
        name:
          type: string
          description: A label for the host to show people, such as `VS Code` or `marimo`. Two hosts can share a name; the filename is the identity.
          example: marimo
        url:
          type: string
          description: Where the host's API is. The scheme is `http`, and the host part is `127.0.0.1` or `[::1]`, written exactly that way.
          example: http://127.0.0.1:2718/api/marimo/v1
        token:
          type: string
          minLength: 1
          description: The secret a client sends to prove it read the record.
    Process:
      type: object
      description: |
        The process that wrote a record. A client checks that a process
        with this `pid` that started at `started_at` still exists. If it
        does not, the record is stale and may be removed.
      required: [pid, started_at]
      properties:
        pid:
          type: integer
          format: int64
          minimum: 1
          description: The process id.
        started_at:
          type: string
          format: date-time
          description: When the process started.
    ObjectType:
      type: string
      description: |
        The kinds a stream carries, and the values `types` accepts. The
        catalog stream carries host, project, notebook, runtime, and
        attachment. A notebook's stream carries notebook, document,
        cell, runtime, attachment, run, execution, console,
        display, variable, and custom. Custom events describe occurrences
        rather than object state.
      enum: [host, project, notebook, document, cell, runtime, attachment, run, execution, console, display, variable, custom]
    Custom:
      type: object
      description: |
        A notebook occurrence with a producer-defined payload. It is replayed
        while event history is retained, but is never included in snapshots
        and does not belong to a run. The notebook is identified by the stream.
      required: [type, data]
      properties:
        type:
          type: string
          minLength: 1
          description: A namespaced event type under a namespace the producer controls, such as `marimo.pair.agent-message`. Clients ignore types they do not recognize while retaining the stream cursor.
        data:
          description: Any JSON value, including null. The producer defines its schema and consumers of the type validate it.
    Host:
      type: object
      description: |
        What the host can do. There is exactly one host object, and it is
        the first object in a snapshot when the filter includes `host`.
        A resumed stream only sends it if its operations changed since
        the cursor. The host sends it again if its operations change.
      required: [operations]
      properties:
        operations:
          type: array
          items: { type: string }
          description: The operations this host implements, such as `runtime.start`. Whether a client may call one on a given project or notebook is that object's `operations`. Clients accept names they do not recognize.
    ProjectStatus:
      type: string
      description: |
        How far a host has gotten finding the notebooks in a project.
        While it is `indexing`, more notebooks are coming. Once it is
        `indexed`, the host believes it has found every notebook under the
        root. A `partial` project is one the host stopped scanning on
        purpose, or one with something it could not read.
      enum: [indexing, indexed, partial]
    Project:
      type: object
      description: A project is a group of notebooks that the host presents together, usually a directory.
      required: [id, name, root, status, message, operations]
      properties:
        id: { $ref: '#/components/schemas/ProjectId' }
        name:
          type: string
          description: A label to show people, usually the name of the root directory.
        root:
          type: [string, 'null']
          description: The absolute path of the project's directory, written the way the host's operating system writes paths. Null when the project has no directory.
        status: { $ref: '#/components/schemas/ProjectStatus' }
        message:
          type: [string, 'null']
          description: Why the host stopped scanning. Null unless `status` is `partial`.
        operations:
          type: array
          items: { type: string }
          description: Operations this client may call on the project, today `notebook.create`. A subset of `host.operations`, narrowed by permission and never by state. The host sends the project again when it changes.
    Notebook:
      type: object
      description: |
        A notebook is a document and its results as the host knows them,
        usually backed by a file. Its kernel, when it has one, is a
        separate object, the runtime. A host sends at most one `notebook`
        event per second for the same notebook, since `updated_at`
        changes on every save.
      required: [id, project_id, path, name, operations, updated_at]
      properties:
        id: { $ref: '#/components/schemas/NotebookId' }
        project_id: { $ref: '#/components/schemas/ProjectId' }
        path:
          type: [string, 'null']
          description: The file's path relative to the project root, written the way the host's operating system writes paths. Null when the notebook has no file, such as one not yet saved, or one deleted while a runtime still refers to it.
        name:
          type: string
          description: A label to show people. Derived from the filename when the host has nothing better.
        operations:
          type: array
          items: { type: string }
          description: Operations this client may call on the notebook, such as `notebook.edit` or `runtime.start`. A subset of `host.operations`, narrowed by permission and never by state; whether a runtime is attached shows in the `runtime` object, and preconditions still apply when an operation is called. The host sends the notebook again when it changes.
        updated_at:
          type: [string, 'null']
          format: date-time
          description: When the file was last modified, as of the host's last look at it. Null when the host does not know.
    RuntimeStatus:
      type: string
      description: |
        Where a runtime is in its life. A `starting` runtime is bringing
        its kernel up. A `running` runtime accepts work. A `terminating`
        runtime is shutting its kernel down. A `failed` runtime could not
        start, or its kernel exited unexpectedly. A runtime that has
        ended is removed rather than given a status.
      enum: [starting, running, terminating, failed]
    Runtime:
      type: object
      description: |
        A runtime is a kernel attached to one notebook, and a notebook has
        at most one. It ends when a client or the host stops it or its
        process exits, and the host then sends `runtime.removed`. Every start and restart creates
        a new runtime with a new id. Results carry their producer's runtime
        id so clients can tell which are live.
      required: [id, notebook_id, status, message, marimo_version, started_at]
      properties:
        id: { $ref: '#/components/schemas/RuntimeId' }
        notebook_id: { $ref: '#/components/schemas/NotebookId' }
        status: { $ref: '#/components/schemas/RuntimeStatus' }
        message:
          type: [string, 'null']
          description: A note about the current status, such as progress while `starting` or the reason when `failed`. Null otherwise.
        marimo_version:
          type: [string, 'null']
          description: The version of marimo running the kernel. Null until the host knows it.
        started_at:
          type: string
          format: date-time
          description: When this runtime started.
    Attachment:
      type: object
      description: |
        An attachment is a consumer connected to a notebook, such as a
        browser tab, an editor, or an agent. Opening the notebook's stream
        creates one. It is removed when that connection closes, and not
        when the notebook's runtime stops or restarts. Each stream has its
        own attachment, even when several share a client identity.
      required: [id, notebook_id, kind, name, since]
      properties:
        id: { $ref: '#/components/schemas/AttachmentId' }
        notebook_id: { $ref: '#/components/schemas/NotebookId' }
        identity:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[!-~]+$'
          description: |
            The opaque client identity supplied by `Marimo-Attachment-Identity`.
            Omitted when none was supplied. Consumers can group attachments
            with the same identity within a host. It does not identify an
            individual connection or change its lifetime.
        kind:
          type: string
          pattern: '^[a-z0-9-]+$'
          description: What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.
        name:
          type: [string, 'null']
          maxLength: 256
          description: A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.
        since:
          type: string
          format: date-time
          description: When it attached.
    Lifecycle:
      type: string
      description: |
        Where a run or execution is in its lifecycle. An execution is
        `queued` until it starts, `running` while code executes, and
        `completed` once it has ended. How it ended is its `outcome`.
      enum: [queued, running, completed]
    RunOutcome:
      type: string
      description: |
        How a run ended. `succeeded` means its work settled without an
        execution error or interruption. `failed` means an execution
        failed or the host could not finish the cycle. `interrupted`
        means the cycle was cut short by interruption, even if an earlier
        execution failed. Execution outcomes retain their individual results.
      enum: [succeeded, failed, interrupted]
    Run:
      type: object
      description: |
        One bounded cycle of notebook work initiated by an action. It
        includes synchronous callbacks and reactive work owned and awaited
        by the runtime's scheduler. Context inherited by an independent task
        records provenance, not ownership of the cycle. The host completes it
        only after all member executions have ended and scheduling for the
        cycle has finished. It never reopens or acquires new executions.
        Independently triggered later work starts another run, even when
        its cause belongs to an earlier run. Every consumer attached to
        the notebook sees it.

        Retention is up to the host and independent of replay history.
        Hosts SHOULD retain ephemeral results briefly after completion to
        allow reconnection. Runs, executions, and items each have removal
        events; a cell result may outlive its run.
      required: [id, notebook_id, caused_by, status, outcome, started_at, completed_at]
      properties:
        id: { $ref: '#/components/schemas/RunId' }
        notebook_id: { $ref: '#/components/schemas/NotebookId' }
        caused_by:
          oneOf: [{ $ref: '#/components/schemas/ExecutionId' }, { type: 'null' }]
          description: The execution that caused this runtime-scheduled run. This records provenance, not membership in that execution's run, and does not extend the earlier run's lifetime. Null for a client request or when the runtime does not know the source.
        status:
          $ref: '#/components/schemas/Lifecycle'
          description: Queued until the first execution starts, running until the cycle has settled or been terminated, and completed once all member executions are terminal and no more can be scheduled in this run. A run can complete with no executions.
        outcome:
          oneOf: [{ $ref: '#/components/schemas/RunOutcome' }, { type: 'null' }]
          description: Null until completed, then final. Published with the terminal status and completed_at. An execution failure does not complete a run while other work remains. Interruption must have taken effect, not merely been requested.
        started_at:
          type: [string, 'null']
          format: date-time
          description: When the first execution started. Null if none has started.
        completed_at:
          type: [string, 'null']
          format: date-time
          description: When the run ended. Null until the run is `completed`.
    DisplayData:
      type: object
      description: A rendered value.
      required: [mimetype, data]
      properties:
        mimetype:
          type: string
          description: The format of `data`, such as `text/html` or `image/png`.
          example: text/html
        data:
          type: string
          description: The rendered value. JSON mimetypes are encoded as text; binary mimetypes are base64. Never a URL only the runtime can serve.
    Variable:
      type: object
      description: |
        A name a cell's execution bound in the notebook's namespace, with
        the revision of its value. The execution binds it as it ends, and
        the item is removed with the execution. An update, as when a
        state setter runs or a client sets a value, advances the revision
        without binding again, and the producer sends the item again with
        the same id. Hosts publish a cell execution's variables before its
        `completed` status, and remove a cell's previous execution and
        its items before publishing the next one. A scratch execution's
        names live only while it runs, so it publishes no variables.
      required: [id, execution_id, name, revision, type, preview]
      properties:
        id: { $ref: '#/components/schemas/ItemId' }
        execution_id:
          $ref: '#/components/schemas/ExecutionId'
          description: The execution that bound the name.
        name:
          type: string
          description: The name in the namespace.
        revision: { $ref: '#/components/schemas/Revision' }
        type:
          type: [string, 'null']
          description: The runtime's label for the value's type. A host may leave it null.
        preview:
          type: [string, 'null']
          description: A short rendering of the value. A host may leave it null.
    Revision:
      type: object
      description: |
        A variable's value at a point in time. Two revisions are equal
        when `execution` and `update` are equal. Clients compare
        revisions for equality.
      required: [execution, update]
      properties:
        execution:
          $ref: '#/components/schemas/ExecutionId'
          description: The execution whose evaluation produced the value. Usually the variable's `execution_id`, and earlier when the runtime carried the value forward.
        update:
          type: integer
          minimum: 0
          description: How many times the value has been updated since it was produced. Zero at binding.
    Position:
      type: object
      description: A position within code, using LSP coordinates.
      required: [line, character]
      properties:
        line:
          type: integer
          minimum: 0
          description: Zero-based line within the code.
        character:
          type: integer
          minimum: 0
          description: Zero-based offset in the line, in UTF-16 code units.
    Range:
      type: object
      description: A span within code.
      required: [start, end]
      properties:
        start: { $ref: '#/components/schemas/Position' }
        end:
          $ref: '#/components/schemas/Position'
          description: Exclusive end. Equal to start when only a point is known.
    Related:
      type: object
      description: A cell involved in an error, possibly the one carrying it.
      required: [cell_id, range, message]
      properties:
        cell_id: { $ref: '#/components/schemas/CellId' }
        range:
          oneOf: [{ $ref: '#/components/schemas/Range' }, { type: 'null' }]
          description: Where in that cell, when known.
        message:
          type: string
          description: What that cell contributes, such as `reads x from C`.
    Error:
      type: object
      description: |
        A problem shaped like an LSP diagnostic. Further members are
        kind-specific, as in Problem Details, and a client ignores
        members it does not know.
      required: [kind, message, source, severity, range, name, traceback, related]
      properties:
        kind:
          type: string
          description: The producer's identifier, scoped by source. Open; this protocol defines `exception`, `interrupted`, and `internal` for executions. Clients show unrecognized kinds as plain errors.
        message:
          type: string
          description: A description of the error to show people.
        source:
          type: [string, 'null']
          description: Who produced it, such as `marimo` or a SQL analyzer. Scopes kind.
        severity:
          type: string
          enum: [error, warning, information, hint]
          description: Error unless the producer says otherwise. Only error affects scheduling.
        range:
          oneOf: [{ $ref: '#/components/schemas/Range' }, { type: 'null' }]
          description: Where in the code, when known.
        name:
          type: [string, 'null']
          description: The exception class, such as `ZeroDivisionError`. Set when kind is exception, null otherwise.
        traceback:
          oneOf: [{ $ref: '#/components/schemas/DisplayData' }, { type: 'null' }]
          description: The traceback as rendered by the runtime, plain text or HTML by its mimetype. Null when unavailable or not shown.
        related:
          type: array
          items: { $ref: '#/components/schemas/Related' }
          description: Every involved cell, including this one, in canonical order. Each copy of a cross-cell error carries the same list; clients deduplicate on kind and related cell ids. Empty when the error involves this code alone.
    Outcome:
      description: |
        How an execution ended, tagged on `kind`. A `value` carries the
        execution's value as last rendered; while the execution is
        running it is the value so far, and it is final once the
        execution is `completed`. An `error` carries the error that ended it.
        An `interrupted` execution was cancelled before or during execution. Other
        kinds are defined by later versions of this protocol.
      oneOf:
        - $ref: '#/components/schemas/ValueOutcome'
        - $ref: '#/components/schemas/ErrorOutcome'
        - $ref: '#/components/schemas/InterruptedOutcome'
      discriminator:
        propertyName: kind
        mapping:
          value: '#/components/schemas/ValueOutcome'
          error: '#/components/schemas/ErrorOutcome'
          interrupted: '#/components/schemas/InterruptedOutcome'
    ValueOutcome:
      type: object
      required: [kind, display]
      properties:
        kind:
          type: string
          enum: [value]
        display:
          oneOf: [{ $ref: '#/components/schemas/DisplayData' }, { type: 'null' }]
          description: The value as last rendered. Replaced as it grows. Null when the code produced no value.
    ErrorOutcome:
      type: object
      required: [kind, error]
      properties:
        kind:
          type: string
          enum: [error]
        error: { $ref: '#/components/schemas/Error' }
    InterruptedOutcome:
      type: object
      required: [kind]
      properties:
        kind:
          type: string
          enum: [interrupted]
    Execution:
      type: object
      description: |
        One cell evaluated within a run, or scratch code evaluated once.
        It moves through `queued`, `running`, and `completed`, and ends with
        one outcome. Side effects belong to the execution whose context
        produced them; items can arrive after the execution is completed
        while it remains retained.
      required: [id, run_id, runtime_id, caused_by, cell_id, code, code_hash, depends_on, status, outcome, started_at, completed_at]
      properties:
        id: { $ref: '#/components/schemas/ExecutionId' }
        run_id:
          oneOf: [{ $ref: '#/components/schemas/RunId' }, { type: 'null' }]
          description: The run that owns this execution. Every live execution belongs to exactly one run. May name a run the host has dropped. Null only for a restored result whose run is unknown.
        runtime_id:
          oneOf: [{ $ref: '#/components/schemas/RuntimeId' }, { type: 'null' }]
          description: The runtime that produced this execution. Live when it equals the current runtime's id. Null when the producer is unknown.
        caused_by:
          oneOf: [{ $ref: '#/components/schemas/ExecutionId' }, { type: 'null' }]
          description: The execution in the same run that caused this one. Null for executions requested directly.
        cell_id:
          oneOf: [{ $ref: '#/components/schemas/CellId' }, { type: 'null' }]
          description: The cell this execution belongs to. Null for scratch code, a cell outside the document.
        code:
          type: [string, 'null']
          description: The submitted code for an execution with no cell. Null for a cell's execution; its source is available through the cell when the host exposes it.
        code_hash:
          $ref: '#/components/schemas/Etag'
          description: The `code_hash` of the code that was evaluated, computed as a cell's is.
        depends_on:
          type: object
          additionalProperties:
            oneOf: [{ $ref: '#/components/schemas/Revision' }, { type: 'null' }]
          description: The variables the execution used, by name, each at the revision the runtime holds its result valid against. Null for a name no retained cell execution had bound. Empty while queued, stamped as the execution ends, and final from then on.
        status: { $ref: '#/components/schemas/Lifecycle' }
        outcome:
          oneOf: [{ $ref: '#/components/schemas/Outcome' }, { type: 'null' }]
          description: How the execution ended. Null while queued; while running, a value carries the display so far; final once completed.
        started_at:
          type: [string, 'null']
          format: date-time
          description: When the code started executing. Null while queued and for an execution that never ran.
        completed_at:
          type: [string, 'null']
          format: date-time
          description: When the execution ended. Null until it is completed.
    Console:
      type: object
      description: |
        Text an execution wrote to stdout or stderr. Items are ordinary
        objects: a producer replaces one by sending it again with the
        same id, and items are removed with their execution.
      required: [id, execution_id, seq, name, text]
      properties:
        id: { $ref: '#/components/schemas/ItemId' }
        execution_id: { $ref: '#/components/schemas/ExecutionId' }
        seq:
          type: integer
          minimum: 0
          description: Position among the execution's items, increasing in the order they were produced.
        name:
          type: string
          enum: [stdout, stderr]
          description: Which stream the text went to.
        text:
          type: string
          description: The text, exactly as written.
    Display:
      type: object
      description: |
        A value an execution showed as a side effect, such as a figure
        from `plt.show()`. A producer replaces one by sending it again
        with the same id, which is how a progress bar updates in place.
      required: [id, execution_id, seq, mimetype, data]
      properties:
        id: { $ref: '#/components/schemas/ItemId' }
        execution_id: { $ref: '#/components/schemas/ExecutionId' }
        seq:
          type: integer
          minimum: 0
          description: Position among the execution's items, increasing in the order they were produced.
        mimetype:
          type: string
          description: The format of `data`, such as `image/png`.
        data:
          type: string
          description: The rendered value. JSON mimetypes are encoded as text; binary mimetypes are base64. Never a URL only the runtime can serve.
    Etag:
      type: string
      description: |
        An identifier derived from content, so that every host, kernel,
        and store computes the same value for the same state. It is the
        first 16 hexadecimal characters, in lower case, of SHA-256 over
        the UTF-8 encoding of a canonical text. Each etag says what its
        text is; a text made of several values is those values joined by
        newlines. Clients do not compute etags. They read them from the
        stream and from responses, and send them back as preconditions.
    CellConfig:
      type: object
      description: How a cell is laid out and whether it runs. Every field is always present, so a cell's etag is well defined.
      required: [column, disabled, hide_code, expand_output]
      properties:
        column:
          type: [integer, 'null']
          description: The column the cell sits in, for multi-column layouts. Null in a single column.
        disabled:
          type: boolean
          description: Whether the cell is kept from running.
        hide_code:
          type: boolean
          description: Whether clients hide the code by default. This is a presentation preference; source availability is represented by `Cell.code`.
        expand_output:
          type: boolean
          description: Whether clients show the full output rather than a scrolled box.
    Cell:
      type: object
      description: |
        A unit of code and configuration in the document. A cell event
        fires when its code, name, or config changes. Markdown and SQL
        cells are code that calls `mo.md` or `mo.sql`; a client chooses
        the editor to show.
      required: [id, notebook_id, code, name, config, etag, code_hash, version]
      properties:
        id: { $ref: '#/components/schemas/CellId' }
        notebook_id: { $ref: '#/components/schemas/NotebookId' }
        code:
          type: [string, 'null']
          description: The cell's source code, with newline line endings, or null when the host does not expose source to this client. An empty string is an empty cell. A host normalizes other line endings when it loads a file. Source availability does not grant editing permission; see the notebook's operations.
        name:
          type: string
          description: The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook.
        config: { $ref: '#/components/schemas/CellConfig' }
        etag:
          $ref: '#/components/schemas/Etag'
          description: Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`.
        code_hash:
          $ref: '#/components/schemas/Etag'
          description: Identifies the code alone. Its text is the actual source, even when `code` is null. Withholding source does not change this hash, the cell or document etags, or their versions. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code without needing the source.
        version:
          type: integer
          minimum: 1
          description: The document version at which the cell was created or last changed.
    Document:
      type: object
      description: |
        The document as a whole, without its cells, which are their own
        objects: the cell order and app config. One per notebook,
        and removed with it. The order and the app
        config carry their own etags, so an edit to one does not conflict
        with an edit to the other, or with edits to cells.
      required: [notebook_id, order, app_config, etag, saved_etag, order_etag, app_config_etag, version]
      properties:
        notebook_id:
          $ref: '#/components/schemas/NotebookId'
          description: The notebook this document belongs to.
        order:
          type: array
          items: { $ref: '#/components/schemas/CellId' }
          description: Cell ids in display order. A permutation of the notebook's cells, each appearing exactly once.
        app_config:
          type: object
          additionalProperties: true
          description: Notebook-level settings, the keyword arguments to `marimo.App` such as `width` and `app_title`. Informational for now; no change sets it over this protocol.
        etag:
          $ref: '#/components/schemas/Etag'
          description: Identifies the document as currently applied. Its text is `order_etag`, `app_config_etag`, and every cell's `etag` in order, so it changes when any of them does.
        saved_etag:
          oneOf: [{ $ref: '#/components/schemas/Etag' }, { type: 'null' }]
          description: Identifies the document as last written to the host's store, computed the same way over that state. Equal to `etag` when every accepted change has been persisted. Null when nothing has been persisted, which is the case for a scratch copy.
        order_etag:
          $ref: '#/components/schemas/Etag'
          description: Identifies the order alone. Its text is the cell IDs in order as a JSON array, with no whitespace and strings carrying only the escapes JSON requires. Editing a cell does not change it.
        app_config_etag:
          $ref: '#/components/schemas/Etag'
          description: Identifies the app config alone. Its text is the app config as canonical JSON, with keys sorted by code point, no whitespace, and strings carrying only the escapes JSON requires.
        version:
          type: integer
          minimum: 1
          description: Counts changes to the cells, the order, or the app config. A save does not advance it. Comparable only within one notebook while it is in the catalog.
    Event:
      description: |
        A record, removal, or control message from a host stream.
        The data is decoded JSON. Snapshot records and reset events omit
        the cursor; ready and live events carry it. Unknown event names
        belong to later versions or host extensions.
      oneOf:
        - $ref: '#/components/schemas/HostEvent'
        - $ref: '#/components/schemas/ProjectEvent'
        - $ref: '#/components/schemas/NotebookEvent'
        - $ref: '#/components/schemas/DocumentEvent'
        - $ref: '#/components/schemas/CellEvent'
        - $ref: '#/components/schemas/RuntimeEvent'
        - $ref: '#/components/schemas/AttachmentEvent'
        - $ref: '#/components/schemas/RunEvent'
        - $ref: '#/components/schemas/ExecutionEvent'
        - $ref: '#/components/schemas/ConsoleEvent'
        - $ref: '#/components/schemas/DisplayEvent'
        - $ref: '#/components/schemas/VariableEvent'
        - $ref: '#/components/schemas/CustomEvent'
        - $ref: '#/components/schemas/ProjectRemovedEvent'
        - $ref: '#/components/schemas/NotebookRemovedEvent'
        - $ref: '#/components/schemas/CellRemovedEvent'
        - $ref: '#/components/schemas/RuntimeRemovedEvent'
        - $ref: '#/components/schemas/AttachmentRemovedEvent'
        - $ref: '#/components/schemas/RunRemovedEvent'
        - $ref: '#/components/schemas/ExecutionRemovedEvent'
        - $ref: '#/components/schemas/ConsoleRemovedEvent'
        - $ref: '#/components/schemas/DisplayRemovedEvent'
        - $ref: '#/components/schemas/VariableRemovedEvent'
        - $ref: '#/components/schemas/ResetEvent'
        - $ref: '#/components/schemas/ReadyEvent'
      discriminator:
        propertyName: event
        mapping:
          host: '#/components/schemas/HostEvent'
          project: '#/components/schemas/ProjectEvent'
          notebook: '#/components/schemas/NotebookEvent'
          document: '#/components/schemas/DocumentEvent'
          cell: '#/components/schemas/CellEvent'
          runtime: '#/components/schemas/RuntimeEvent'
          attachment: '#/components/schemas/AttachmentEvent'
          run: '#/components/schemas/RunEvent'
          execution: '#/components/schemas/ExecutionEvent'
          console: '#/components/schemas/ConsoleEvent'
          display: '#/components/schemas/DisplayEvent'
          variable: '#/components/schemas/VariableEvent'
          custom: '#/components/schemas/CustomEvent'
          project.removed: '#/components/schemas/ProjectRemovedEvent'
          notebook.removed: '#/components/schemas/NotebookRemovedEvent'
          cell.removed: '#/components/schemas/CellRemovedEvent'
          runtime.removed: '#/components/schemas/RuntimeRemovedEvent'
          attachment.removed: '#/components/schemas/AttachmentRemovedEvent'
          run.removed: '#/components/schemas/RunRemovedEvent'
          execution.removed: '#/components/schemas/ExecutionRemovedEvent'
          console.removed: '#/components/schemas/ConsoleRemovedEvent'
          display.removed: '#/components/schemas/DisplayRemovedEvent'
          variable.removed: '#/components/schemas/VariableRemovedEvent'
          reset: '#/components/schemas/ResetEvent'
          ready: '#/components/schemas/ReadyEvent'
    HostEvent:
      type: object
      description: A `host` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [host] }
        id: &event_cursor
          type: string
          minLength: 1
          description: The resume cursor. Omitted on snapshot and reset events.
        data: { $ref: '#/components/schemas/HostMessage' }
    ProjectEvent:
      type: object
      description: A `project` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [project] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/ProjectMessage' }
    NotebookEvent:
      type: object
      description: A `notebook` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [notebook] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/NotebookMessage' }
    DocumentEvent:
      type: object
      description: A `document` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [document] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/DocumentMessage' }
    CellEvent:
      type: object
      description: A `cell` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [cell] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/CellMessage' }
    RuntimeEvent:
      type: object
      description: A `runtime` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [runtime] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RuntimeMessage' }
    AttachmentEvent:
      type: object
      description: A `attachment` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [attachment] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/AttachmentMessage' }
    RunEvent:
      type: object
      description: A `run` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [run] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RunMessage' }
    ExecutionEvent:
      type: object
      description: A `execution` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [execution] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/ExecutionMessage' }
    ConsoleEvent:
      type: object
      description: A `console` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [console] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/ConsoleMessage' }
    DisplayEvent:
      type: object
      description: A `display` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [display] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/DisplayMessage' }
    VariableEvent:
      type: object
      description: A `variable` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [variable] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/VariableMessage' }
    CustomEvent:
      type: object
      description: A `custom` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [custom] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/CustomMessage' }
    ProjectRemovedEvent:
      type: object
      description: A `project.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [project.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    NotebookRemovedEvent:
      type: object
      description: A `notebook.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [notebook.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    CellRemovedEvent:
      type: object
      description: A `cell.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [cell.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    RuntimeRemovedEvent:
      type: object
      description: A `runtime.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [runtime.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    AttachmentRemovedEvent:
      type: object
      description: A `attachment.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [attachment.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    RunRemovedEvent:
      type: object
      description: A `run.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [run.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    ExecutionRemovedEvent:
      type: object
      description: A `execution.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [execution.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    ConsoleRemovedEvent:
      type: object
      description: A `console.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [console.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    DisplayRemovedEvent:
      type: object
      description: A `display.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [display.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    VariableRemovedEvent:
      type: object
      description: A `variable.removed` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [variable.removed] }
        id: *event_cursor
        data: { $ref: '#/components/schemas/RemovedMessage' }
    ResetEvent:
      type: object
      description: A `reset` event from a host stream.
      required: [event, data]
      properties:
        event: { type: string, enum: [reset] }
        id: *event_cursor
        data: { type: object, additionalProperties: false }
    ReadyEvent:
      type: object
      description: A `ready` event from a host stream.
      required: [event, data, id]
      properties:
        event: { type: string, enum: [ready] }
        id: *event_cursor
        data: { type: object, additionalProperties: false }
    HostMessage:
      type: object
      description: The data of a `host` event. The host object, plus which request caused the event and when.
      required: [host]
      properties:
        request_id: &request_id
          type: string
          description: The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress.
        time: &time
          type: string
          format: date-time
          description: When the host made this change. Present on live and replayed events; omitted on snapshots.
        host: { $ref: '#/components/schemas/Host' }
    CustomMessage:
      type: object
      description: The data of a `custom` event. This envelope is standardized; the custom type and payload are defined by their producer.
      required: [custom, time]
      properties:
        custom: { $ref: '#/components/schemas/Custom' }
        request_id: *request_id
        time:
          type: string
          format: date-time
          description: When the host emitted this event. Preserved on replay.
    ProjectMessage:
      type: object
      description: The data of a `project` event. The project as it now is.
      required: [project]
      properties:
        request_id: *request_id
        time: *time
        project: { $ref: '#/components/schemas/Project' }
    NotebookMessage:
      type: object
      description: The data of a `notebook` event. The notebook as it now is.
      required: [notebook]
      properties:
        request_id: *request_id
        time: *time
        notebook: { $ref: '#/components/schemas/Notebook' }
    RuntimeMessage:
      type: object
      description: The data of a `runtime` event. The runtime as it now is.
      required: [runtime]
      properties:
        request_id: *request_id
        time: *time
        runtime: { $ref: '#/components/schemas/Runtime' }
    AttachmentMessage:
      type: object
      description: The data of an `attachment` event. The attachment as it now is.
      required: [attachment]
      properties:
        request_id: *request_id
        time: *time
        attachment: { $ref: '#/components/schemas/Attachment' }
    RunMessage:
      type: object
      description: The data of a `run` event. The run as it now is.
      required: [run]
      properties:
        request_id: *request_id
        time: *time
        run: { $ref: '#/components/schemas/Run' }
    ExecutionMessage:
      type: object
      description: The data of an `execution` event. The execution as it now is.
      required: [execution]
      properties:
        request_id: *request_id
        time: *time
        execution: { $ref: '#/components/schemas/Execution' }
    ConsoleMessage:
      type: object
      description: The data of a `console` event. The item as it now is.
      required: [console]
      properties:
        request_id: *request_id
        time: *time
        console: { $ref: '#/components/schemas/Console' }
    DisplayMessage:
      type: object
      description: The data of a `display` event. The item as it now is.
      required: [display]
      properties:
        request_id: *request_id
        time: *time
        display: { $ref: '#/components/schemas/Display' }
    VariableMessage:
      type: object
      description: The data of a `variable` event. The item as it now is.
      required: [variable]
      properties:
        request_id: *request_id
        time: *time
        variable: { $ref: '#/components/schemas/Variable' }
    DocumentMessage:
      type: object
      description: The data of a `document` event. The document as it now is.
      required: [document]
      properties:
        request_id: *request_id
        time: *time
        document: { $ref: '#/components/schemas/Document' }
    CellMessage:
      type: object
      description: The data of a `cell` event. The cell as it now is.
      required: [cell]
      properties:
        request_id: *request_id
        time: *time
        cell: { $ref: '#/components/schemas/Cell' }
    RemovedMessage:
      type: object
      description: |
        The data of a `project.removed`, `notebook.removed`,
        `cell.removed`, `runtime.removed`, `attachment.removed`,
        `run.removed`, `execution.removed`, `console.removed`,
        `display.removed`, or `variable.removed` event. The client deletes the object with this
        id; the event name says which kind it is. Removing a notebook
        removes its document and cells with it, without events of their
        own; the document never has one.
      required: [id]
      properties:
        request_id: *request_id
        time: *time
        id:
          type: string
          description: The id of the object that was removed.
    Problem:
      type: object
      description: |
        An error. Every error response has this one shape, following RFC
        9457, and is served as `application/problem+json`. `status`
        repeats the HTTP status, and `type` says more precisely what went
        wrong. `decisions` appears only when `type` is
        `tag:marimo.io,2026:host/decision-required`. A client ignores
        members it does not recognize. An error never contains a token.
      required: [type, title, status]
      properties:
        type:
          type: string
          description: |
            What kind of problem this is, as a URI. The kinds this
            protocol defines all start with `tag:marimo.io,2026:host/` and
            end with one of `invalid-request` (400), `unauthorized` (401),
            `forbidden` (403), `not-found` (404), `method-not-allowed`
            (405), `not-acceptable` (406), `conflict` (409), `no-runtime`
            (409), `decision-required` (409), `internal` (500), or
            `unsupported-operation` (501). A client that sees a kind it
            does not recognize falls back to `status`.
          example: tag:marimo.io,2026:host/not-found
        title:
          type: string
          description: A short, human-readable name for the kind of problem.
        status:
          type: integer
          minimum: 400
          maximum: 599
          description: The HTTP status code of the response.
        detail:
          type: string
          description: A human-readable explanation of what went wrong this time.
        decisions:
          type: array
          items: { $ref: '#/components/schemas/Decision' }
          description: The choices the client has to make before the host can carry out the request. Only present for `decision-required`.
        edit:
          $ref: '#/components/schemas/EditConflict'
          description: Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit, a save, or a run of cells.
    Decision:
      type: object
      description: |
        A question the host needs answered before it can carry out a
        request. The client answers by repeating the request with
        `decisions` in the body, mapping this `id` to the `id` of an
        option.
      required: [id, prompt, options]
      properties:
        id:
          type: string
          description: Identifies the question when the client answers it.
        prompt:
          type: string
          description: The question, worded for a person.
          example: Where should forecasts.py run?
        options:
          type: array
          items: { $ref: '#/components/schemas/DecisionOption' }
          description: The possible answers.
    DecisionOption:
      type: object
      description: One possible answer to a decision.
      required: [id, label]
      properties:
        id:
          type: string
          description: Identifies this answer.
        label:
          type: string
          description: Text to show a person.
          example: Sandbox from the notebook's dependencies
    CreateNotebookRequest:
      type: object
      description: The notebook's own fields, minus what the host assigns. A project with a root requires `path`; one without requires `name`.
      required: [project_id]
      properties:
        project_id: { $ref: '#/components/schemas/ProjectId' }
        path:
          type: string
          description: Where to put the file, relative to the project root and written the way the host's operating system writes paths.
          example: analysis.py
        name:
          type: string
          description: A label to show people. In a project with a root it defaults to the filename.
    UpdateNotebookRequest:
      type: object
      description: The fields to change. At least one is present.
      properties:
        path:
          type: string
          description: The new location, relative to the project root and written the way the host's operating system writes paths.
        name:
          type: string
          description: The new label to show people.
    OpenNotebookResponse:
      type: object
      required: [url]
      properties:
        url:
          type: string
          description: The URL the host used to show the notebook. It never contains the host's token.
    StartRuntimeRequest:
      type: object
      properties:
        decisions:
          type: object
          additionalProperties: { type: string }
          description: |
            Answers to the questions in a `decision-required` problem.
            Each key is a decision's `id` and each value is the `id` of
            the chosen option. A client that already knows its choices can
            send them the first time.
          example: { environment: sandbox }
    CellConfigInput:
      type: object
      description: A cell's settings as a client writes them. A field left out takes its default.
      properties:
        column:
          type: [integer, 'null']
          default: null
        disabled:
          type: boolean
          default: false
        hide_code:
          type: boolean
          default: false
        expand_output:
          type: boolean
          default: false
    CellInput:
      type: object
      description: A cell as a client writes it. Code must be a string, even when the host withholds source in cell records. Null is not an edit or a request to preserve existing source. The host derives the etags.
      required: [id, code]
      properties:
        id:
          $ref: '#/components/schemas/CellId'
          description: The cell's id. A client chooses the id of a cell it creates.
        code:
          type: string
          description: The cell's source code.
        name:
          type: string
          default: _
          description: The cell's name. `_` for an anonymous cell.
        config:
          $ref: '#/components/schemas/CellConfigInput'
    PutCell:
      type: object
      description: Replaces a whole cell, or creates one.
      required: [kind, base_etag, cell]
      properties:
        kind:
          type: string
          enum: [put_cell]
        base_etag:
          type: [string, 'null']
          description: The cell's etag as last read, `*` to skip the check, or null to create the cell. Null when the cell exists, or an etag when it does not, is a `conflict`.
        cell: { $ref: '#/components/schemas/CellInput' }
        after:
          $ref: '#/components/schemas/CellId'
          description: The cell a created cell goes after. Ignored for an existing cell.
        before:
          $ref: '#/components/schemas/CellId'
          description: The cell a created cell goes before. Ignored for an existing cell. With neither `after` nor `before`, a created cell goes at the end.
    DeleteCell:
      type: object
      description: Removes a cell.
      required: [kind, id, base_etag]
      properties:
        kind:
          type: string
          enum: [delete_cell]
        id:
          $ref: '#/components/schemas/CellId'
          description: The cell to remove.
        base_etag:
          type: string
          description: The cell's etag as last read, or `*`.
    SetOrder:
      type: object
      description: Replaces the cell order.
      required: [kind, base_etag, order]
      properties:
        kind:
          type: string
          enum: [set_order]
        base_etag:
          type: string
          description: The document's `order_etag` as last read, or `*`.
        order:
          type: array
          items: { $ref: '#/components/schemas/CellId' }
          description: Every cell id exactly once, in the new order, counting cells this edit creates and leaving out cells it deletes.
    Change:
      description: One change to the document, tagged on `kind`.
      oneOf:
        - $ref: '#/components/schemas/PutCell'
        - $ref: '#/components/schemas/DeleteCell'
        - $ref: '#/components/schemas/SetOrder'
      discriminator:
        propertyName: kind
        mapping:
          put_cell: '#/components/schemas/PutCell'
          delete_cell: '#/components/schemas/DeleteCell'
          set_order: '#/components/schemas/SetOrder'
    EditRequest:
      type: object
      required: [changes]
      properties:
        changes:
          type: array
          items: { $ref: '#/components/schemas/Change' }
          description: The changes, applied in order as one unit.
    CellVersion:
      type: object
      description: A cell's etags and version after an edit.
      required: [etag, code_hash, version]
      properties:
        etag: { $ref: '#/components/schemas/Etag' }
        code_hash: { $ref: '#/components/schemas/Etag' }
        version:
          type: integer
          minimum: 1
          description: The cell's version after the edit.
    EditResponse:
      type: object
      description: The document as an edit or save left it, or at a later revision, and the cells it touched.
      required: [document, cells]
      properties:
        document: { $ref: '#/components/schemas/Document' }
        cells:
          type: object
          additionalProperties:
            oneOf: [{ $ref: '#/components/schemas/CellVersion' }, { type: 'null' }]
          description: The version of each cell the request created or changed, by id, and null for each cell it deleted.
    EditConflict:
      type: object
      description: The first stale change of an edit or run, and the state the host holds.
      required: [change, cell, document]
      properties:
        change:
          type: integer
          minimum: 0
          description: The index of the stale change in the request's `changes`, or of the stale cell in a run's `cells`. `0` for a save with a stale `If-Match`.
        cell:
          oneOf: [{ $ref: '#/components/schemas/Cell' }, { type: 'null' }]
          description: The cell the change named, as it now is. Null when the document does not have it, or when the change named the order.
        document: { $ref: '#/components/schemas/Document' }
    SaveRequest:
      type: object
      description: What a save needs from the client, which is nothing until the host asks a question. `{}` is the usual body.
      properties:
        decisions:
          type: object
          additionalProperties: { type: string }
          description: Answers to the questions in a `decision-required` problem, as for `runtime.start`.
    RunRequest:
      type: object
      description: What to run, exactly one of `code` and `cells`.
      properties:
        code:
          type: string
          description: Python code to run as scratch code.
        cells:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/RequestedCell' }
          description: Cells of the document to run, in no particular order. The runtime's execution configuration determines whether dependent cells run too.
    RequestedCell:
      type: object
      required: [id]
      properties:
        id: { $ref: '#/components/schemas/CellId' }
        code_hash:
          $ref: '#/components/schemas/Etag'
          description: The cell's `code_hash` as last read. A cell whose code differs is a `conflict`. Absent, the cell runs as it is.