Skip to content
SpiceBook

Notebooks

List Notebooks

Section titled “List Notebooks”
GET /api/notebooks

Returns an array of notebook summaries:

[
  {
    "id": "rc-low-pass-a1b2c3d4",
    "title": "RC Low-Pass Filter",
    "engine": "ngspice",
    "tags": ["filter", "rc"],
    "cell_count": 3,
    "modified": "2026-02-13T18:30:00+00:00"
  }
]

Create Notebook

Section titled “Create Notebook”
POST /api/notebooks

Request body:

{
  "title": "My Circuit",
  "engine": "ngspice"
}

Both fields are optional. Defaults: title = "Untitled Notebook", engine = "ngspice". Supported engines: "ngspice", "ltspice".

Response 201 — the full notebook with an auto-generated id:

{
  "id": "my-circuit-f8e2a91b",
  "spicebook_version": "2026-02-13",
  "metadata": {
    "title": "My Circuit",
    "engine": "ngspice",
    "tags": [],
    "created": "2026-02-13T18:30:00+00:00",
    "modified": "2026-02-13T18:30:00+00:00"
  },
  "cells": [
    {
      "id": "cell-a1b2c3d4e5f6",
      "type": "markdown",
      "source": "# My Circuit\n\nAdd SPICE cells below to begin simulating.",
      "outputs": []
    }
  ]
}

New notebooks start with a single markdown cell containing a heading.

Get Notebook

Section titled “Get Notebook”
GET /api/notebooks/{notebook_id}

Response 200 — full notebook object (same shape as the create response, without the top-level id wrapper).

Update Notebook

Section titled “Update Notebook”
PUT /api/notebooks/{notebook_id}

Request body — full notebook object. This replaces the entire notebook, including all cells and metadata.

Response 200 — the saved notebook.

Delete Notebook

Section titled “Delete Notebook”
DELETE /api/notebooks/{notebook_id}

Response 204 — no content.

Compose Notebook

Section titled “Compose Notebook”
POST /api/notebooks/compose

Creates a fully-populated notebook with multiple cells in a single call. This is the preferred way to create notebooks programmatically.

Request body:

{
  "title": "RC Low-Pass Filter",
  "engine": "ngspice",
  "tags": ["filter", "rc", "analog"],
  "cells": [
    {
      "type": "markdown",
      "source": "# RC Low-Pass Filter\n\nA simple first-order low-pass filter."
    },
    {
      "type": "spice",
      "source": "V1 in 0 AC 1\nR1 in out 1k\nC1 out 0 1u\n.ac dec 100 1 1meg\n.end"
    },
    {
      "type": "markdown",
      "source": "## Analysis\n\nThe -3dB cutoff is at f = 1/(2*pi*R*C) = 159 Hz."
    }
  ],
  "run": false
}
FieldTypeDefaultDescription
titlestring"Untitled Notebook"Notebook title
enginestring"ngspice"Simulation engine
tagsstring[][]Searchable tags
cellsobject[](required)Cells to create, each with type and source
runbooleanfalseIf true, execute each SPICE cell after creation

Response 201 — same shape as POST /api/notebooks.

When run is true, each SPICE cell is executed sequentially using the notebook’s engine. Simulation results are stored in each cell’s outputs array. Non-SPICE cells are unaffected.