# AMSpiriT — Web Server Endpoint Tests

Each section issues one real HTTP request to 127.0.0.1:8765 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.
Topics frame z80_bp basic_bp pause reset
Pause log on breakpoint Log frame events
frame: 0 z80_bp: 0 basic_bp: 0 pause: 0 reset: 0
— connect to start receiving events —

## GET Endpoints

GET /api/ping
Connection probe + emulator status (fps, paused, cpc_model, crtc_type). 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)
—
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 + 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=0 = central RAM, bank=1..N = extended page N-1. view=cpu = memory as the Z80 sees it (ROM overlays + banking).
addr len bank view
—
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.
verbose
—
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

POST/api/step
Execute exactly one Z80 instruction, then re-pause (no body). Pause the emulator first.
—
POST/api/render
Change monitor preset / screen type / CRT shader params. Any subset of keys.
JSON body {"monitor":1}
—
POST/api/basic_step?mode=…
Step the BASIC program to the next statement (mode=stmt) or next line (mode=line). Pause first.
mode
—
POST/api/basic_bp
Set the BASIC line-breakpoint set (comma-separated line numbers; empty = clear all)
lines
—
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)
target
—
POST /api/config
Queue a config change. Fields: cpc_model, crtc_type, rom_lang, paused, do_soft_reset, do_hard_reset
JSON body {"paused":true}
—
POST /api/keytype
Queue a string for autotype (injected as key events on the CPC)
text
—
POST /api/keypress
Press a single CPC virtual key by VK number (0x00–0xFF, see CORE_rVK_* constants)
vk (hex)
—
POST /api/ram
Write bytes to CPC RAM. data = hex string. exec=true → also set PC to entry.
addr data (hex) exec
entry
—
POST /api/exec
Set Z80 PC to addr and resume execution (no RAM write)
addr
—
POST /api/basic?reset=…&run=…
Inject BASIC source (raw text body, not JSON). reset=1 → hard reset first. run=1 → RUN after inject.
reset
run
BASIC src 10 PRINT "HELLO FROM WEB" 20 GOTO 10
—
POST /api/script?lang=…
Run a CSL or Lua script (raw text body). ?lang=lua for Lua, default = CSL.
lang
script -- CSL example wait(20)
—
POST /api/disk — action: create
Create a blank disk image in the given drive (0=A, 1=B)
drive
—
POST /api/disk — action: save (triggers browser download)
Save current disk image as .dsk file (response is binary — triggers download via <a>)
drive
—
POST /api/lang
Change UI language {"lang":"en"|"fr"|"es"|"de"}
lang
—
POST /api/keymap
Remap a key: kc (keycode hex), vk (CPC VK for unshifted), vk_s (shifted), nomod (bool)
JSON body {"kc":"0x61","vk":65,"vk_s":65,"nomod":false}
—

## DELETE Endpoints

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