AMSpiriT — Web Server Endpoint Tests

Each section issues one real HTTP request to 127.0.0.1:6128 and shows the raw response.

Server-Sent Events — /api/events

SSE /api/events disconnected
Persistent push stream. The server sends events as they occur. No polling needed. z80_bp carries the registers and ticks at the stop: to run to the next breakpoint, keep this open and resume (POST /api/config {"paused":false}).
frame: 0 z80_bp: 0 basic_bp: 0 pause: 0 reset: 0
— connect to start receiving events —

Self-Documentation — /api/doc

GET /api/doc
List every documented endpoint (path, HTTP methods, one-line summary). Machine-readable contract for the whole API below — source of truth: amspirit-helpers/src/web_doc.cpp.
—
GET /api/doc/<name>
Detail for one endpoint (all its HTTP methods): params (query/body, type, required/default) and response shape. <name> is the path segment under /api/, e.g. "config" for /api/config.
—

GET Endpoints

GET /api/ping
Connection probe + emulator status (fps, paused, cpc_model, crtc_type, ticks = NOPs since the last hard reset/SNA load/rewind, applied_cmd_seq). Used by the UI for the connection overlay.
—
GET /api/z80
Z80 registers snapshot (PC, SP, AF/BC/DE/HL + alternates, IX, IY, I, R, IFF1/2, IM) + ticks
—
GET /api/ga
Gate Array state (video mode, border, HBL/VBL, ink palette)
—
GET /api/crtc
CRTC registers snapshot (R0–R17, internal counters, VMA, HSYNC/VSYNC)
—
GET /api/psg
PSG AY-3-8912 state (tone periods, volumes, mixer, noise, envelope)
—
GET /api/fdc
FDC PD765 state (MSR, SR0–SR2, motor, active drive)
—
GET /api/state
Combined snapshot: z80 + ga + crtc + psg + fdc + beam + emu (aggregate of the sub-endpoints above)
—
GET /api/config
Current CORE_PARAM_IN values (CPC model, CRTC type, ROM lang…)
—
GET /api/ram?addr=…&len=…&bank=…
Hex dump of CPC RAM. bank = 16K bank index: 0–3 = base 64K, 4+ = extension (B00–B103); an addr above 0x3FFF carries into it. view=cpu = memory as the Z80 sees it (ROM overlays + banking).
—
GET /api/script
Script running status + last error message
—
GET /api/lang
Current UI language {"lang":"en"|"fr"|"es"|"de"}
—
GET /api/keymap
Full key mapping table (keycode → CPC virtual key)
—
GET /api/basic_state
BASIC interpreter state (current line, variables…)
—
GET /api/basic_export?verbose=…
BASIC source detokenised from RAM (text/plain). verbose=1 adds token annotations.
—
GET/api/history
Last 20 executed Z80 instructions [{pc,hex}] (opcode bytes from CPU-visible memory)
—
GET/api/codemap
65536-bit bitmap (8192 bytes hex) of addresses where an instruction has executed (code/data zones)
—
GET/api/memmap
ROM/RAM mapping per 16 KB region + RAM banking config (rmr, ram_mode, ram_page)
—
GET/api/render
CRT monitor preset, screen type and shader parameters
—
GET/api/basic_listing
Structured listing: lines + statements with RAM address ranges + referenced variables
—
GET/api/scan_ptr
Diagnostic: RAM words pointing into the BASIC program, with the line each points into
—

POST Endpoints

Every command below answers {"ok":true,"cmd_seq":N} as soon as it is queued. It has taken effect once GET /api/ping's emu.applied_cmd_seq is >= N (a step has then executed; a resume or a BASIC step has started).
POST/api/step
Execute exactly one Z80 instruction, then re-pause (no body). Pause the emulator first. Runs the instruction even when a breakpoint sits on the current PC.
—
POST/api/z80_bp
Replace the Z80 PC breakpoint set: comma-separated CPU addresses (decimal or 0x…) or Bnn:hhhh locations; empty = clear all. Resuming never re-breaks on the PC it resumes from.
—
POST/api/media?name=…&drive=…&crtc=…
Load a media file (SNA/DSK/HFE/IPF/CPR/CRO/BIN) from the raw body. crtc (SNA only): sna = use the CRTC the snapshot names (default), keep = keep the CRTC emulated before the load (same side of the Plus boundary only: CRTC 3 vs 0/1/2/4). Check emu.crtc_type once applied.
—
POST/api/render
Change monitor preset / screen type / CRT shader params. Any subset of keys.
—
POST/api/basic_step?mode=…
Step the BASIC program to the next statement (mode=stmt) or next line (mode=line). Pause first.
—
POST/api/basic_bp
Set the BASIC line-breakpoint set (comma-separated line numbers; empty = clear all)
—
POST/api/basic_runto?line=… | ?addr=…
One-shot run to a BASIC line (line=) or statement address (addr=, an 0xAE1B value from /api/basic_listing)
—
POST /api/config
Queue a config change. Fields: cpc_model, crtc_type, rom_lang, paused, do_soft_reset, do_hard_reset
—
POST /api/keytype
Queue a string for autotype (injected as key events on the CPC)
—
POST /api/keypress
Press a single CPC virtual key by VK number (0x00–0xFF, see CORE_rVK_* constants)
—
POST /api/ram
Write bytes to CPC RAM. data = hex string. exec=true → also set PC to entry. Queued (several calls in the same tick all apply, in order) — response includes a "seq"; poll /api/state's emu.ram_apply_seq until it reaches that value before trusting a readback (or use its cmd_seq, like any command).
—
POST /api/exec
Set Z80 PC to addr and resume execution (no RAM write). Same queue/"seq" contract as POST /api/ram above.
—
POST /api/basic?reset=…&run=…
Inject BASIC source (raw text body, not JSON). reset=1 → hard reset first. run=1 → RUN after inject.
—
POST /api/script?lang=…
Run a CSL or Lua script (raw text body). ?lang=lua for Lua, default = CSL.
—
POST /api/disk — action: create
Create a blank disk image in the given drive (0=A, 1=B)
—
POST /api/disk — action: save (triggers browser download)
Save current disk image as .dsk file (response is binary — triggers download via <a>)
—
POST /api/lang
Change UI language {"lang":"en"|"fr"|"es"|"de"}
—
POST /api/keymap
Remap a key: kc (keycode hex), vk (CPC VK for unshifted), vk_s (shifted), nomod (bool)
—

DELETE Endpoints

DELETE /api/script
Abort the currently running CSL/Lua script
—
DELETE /api/codemap
Reset the executed-instruction bitmap and the instruction history
—