Everything the Studio window does goes through a local HTTP API and one WebSocket, so you can drive Studio from scripts, CI jobs or other programs without the browser. This page describes the conventions, the binary trace format, every WebSocket event, every endpoint, and worked examples.

• Base URL: http://127.0.0.1:8765 by default (the host and port you started Studio with; see Command Line and Configuration).
• Endpoint list: open http://127.0.0.1:8765/api/docs for a list of every route the running server offers, with its method, parameters and notes. http://127.0.0.1:8765/openapi.json has the same list as an OpenAPI 3 document for tools.
• Requests: POST and PUT bodies are JSON (Content-Type: application/json). Uploads use multipart/form-data with a file field, or send the file itself as the request body with ?filename=NAME (for example curl --data-binary @fw.hex "http://127.0.0.1:8765/api/target/program/upload?programmer=STM32F&filename=fw.hex").
• Responses: JSON, except trace data, which uses the binary frame format below, and file downloads.
• Errors: a non-2xx status with {"detail": "ExceptionType: message"}. Most failures (no scope connected, build failed to start) return status 400. A missing or malformed query, path or file parameter returns 422 with a list instead: {"detail": [{"type": "missing", "loc": ["query", "path"], "msg": "Field required", "input": null}]}.
• Long jobs: captures, glitch sweeps, CPA, builds and downloads start in the background and return immediately. Poll the matching status endpoint or listen on the WebSocket.
• One hardware job at a time: a capture, a glitch sweep and a logic analyser capture cannot run together. Starting a second one returns an error.
• Not found: an unknown notebook, logic channel, decoder or code map item returns 404 with the same {"detail": ...} form.

Note: The API has no authentication. Anyone who can reach the port can control your hardware and run notebook code. Keep the default bind address 127.0.0.1 unless you are on a trusted network.

Trace data (GET /api/traces/{index}, /api/traces/stats, /api/traces/block, /api/analysis/cpa/corr/{b}, /api/codemap/model and trace WebSocket messages) uses one compact format:

For /api/traces/stats the samples are the fields listed in header.fields (mean, std, min, max) one after another, each header.samples long. For /api/traces/block they are the requested traces one after another.

import json, struct
import numpy as np
import requests

def decode(frame: bytes):
    (n,) = struct.unpack_from("<I", frame, 0)
    header = json.loads(frame[4:4 + n])
    samples = np.frombuffer(frame[4 + n:], dtype="<f4")
    return header, samples

header, wave = decode(requests.get("http://127.0.0.1:8765/api/traces/0").content)
print(header["textin"], wave.shape)

Connect to ws://127.0.0.1:8765/ws. Studio sends a hello message with the version and full status, then one message per event. Text frames are JSON with a type field (plus seq and ts); binary frames use the trace frame format with type in the header. Messages you send are ignored.

Each notebook has its own kernel. The optional kernel parameter (query parameter for GET, body field or query parameter for POST) is a notebook path relative to the notebooks folder (the id the Notebook tab uses for that notebook), any other string as a temporary id, or empty for the shared default kernel. Requests without it behave as before, against the default kernel. Kernels are created by the first execute or run that names them; status and variables of a kernel that has not started report it as idle and empty without creating it. POST /api/notebooks/run runs in the notebook's own kernel unless its body names another kernel, and deleting a notebook shuts its kernel down. Cells of all kernels share one queue and run one at a time on the hardware thread.

Everything in the Interfaces tab. Requests for something the connected model does not support return 400 with the reason (Unsupported: ...). Booleans accept true/false, 1/0, yes/no and on/off.

The Logic tab. Sample indices count from the start of the capture; times are in seconds from the trigger. Channels can be given by index or by name.

Code on the Waveform. Sample indices are those of the stored traces.

B=http://127.0.0.1:8765
curl -s -X POST $B/api/scope/connect -H 'Content-Type: application/json' -d '{"kind":"sim"}'
curl -s -X POST $B/api/target/connect -H 'Content-Type: application/json' -d '{"kind":"sim"}'
curl -s -X POST $B/api/capture/start -H 'Content-Type: application/json' -d '{"count":100,"clear":true,"key":"2b7e151628aed2a6abf7158809cf4f3c"}'
sleep 3
curl -s $B/api/traces
curl -s -o traces.npz $B/api/traces/download/npz
curl -s -X POST $B/api/analysis/cpa/start -H 'Content-Type: application/json' -d '{"model":"sbox_hw"}'
sleep 2
curl -s $B/api/analysis/cpa | python3 -c "import json,sys; r=json.load(sys.stdin); print(r['best_key'], r['done'])"

import time
import requests

B = "http://127.0.0.1:8765"
s = requests.Session()

def wait_idle():
    while True:
        job = s.get(f"{B}/api/status").json().get("job") or {}
        if not job.get("running"):
            return
        time.sleep(0.2)

s.post(f"{B}/api/scope/connect", json={"kind": "sim"}).raise_for_status()
s.post(f"{B}/api/target/connect", json={"kind": "sim"}).raise_for_status()
s.post(f"{B}/api/capture/start", json={"count": 100, "clear": True, "key": "2b7e151628aed2a6abf7158809cf4f3c"}).raise_for_status()
wait_idle()

s.post(f"{B}/api/analysis/cpa/start", json={"model": "sbox_hw"}).raise_for_status()
while not (r := s.get(f"{B}/api/analysis/cpa").json()).get("done"):
    time.sleep(0.2)
print("key:", r["best_key"])

r = s.post(f"{B}/api/firmware/build", json={"project": "simpleserial-aes", "platform": "CWLITEARM", "compiler": "gcc"}).json()
while r["state"] == "running":
    time.sleep(0.5)
    r = s.get(f"{B}/api/firmware/build").json()
print(r["state"], r.get("hex"), r.get("size"))
if r["state"] == "ok":
    print(s.post(f"{B}/api/firmware/program", json={}).json())

The compiler and firmware sources must be installed first (see Toolchains and Firmware Sources), otherwise the build call returns an error that says what is missing.

r = s.post(f"{B}/api/kernel/run", json={"code": "import chipwhisperer as cw\nscope = cw.scope()\nlen(studio.traces)"}).json()
print(r["ok"], [o.get("data", {}).get("text/plain") or o.get("text") for o in r["outputs"]])
# the same in the kernel of a notebook (sees the variables its tab in the Notebook tab defined)
r = s.post(f"{B}/api/kernel/run", json={"code": "sorted(k for k in globals() if not k.startswith('_'))", "kernel": "lab/attack.ipynb"}).json()
print(r["kernel"], r["outputs"][-1]["data"]["text/plain"])

import asyncio, json
import websockets

async def main():
    async with websockets.connect("ws://127.0.0.1:8765/ws") as ws:
        async for msg in ws:
            if isinstance(msg, bytes):
                continue  # binary trace frame, decode with decode() above
            ev = json.loads(msg)
            if ev["type"] in ("capture", "log"):
                print(ev)

asyncio.run(main())

See also: MCP Server, Command Line and Configuration.