dosbox-automation API

GET /api/v1/status

Overall emulator status.

{
    "running": true,
    "shutdown_requested": false,
    "is_booted": false,
    "is_shell": true,
    "program": "COMMAND",
    "canonical_name": "COMMAND.COM"
}

GET /api/v1/program/state

Currently running program information.

{
    "segment_name": "DOOM",
    "canonical_name": "DOOM.EXE",
    "is_shell": false,
    "is_booted": false
}

GET /api/v1/dosbox/info

DOSBox version and configuration paths.

POST /api/v1/control/shutdown

Request a graceful shutdown.

POST /api/v1/input/sequence

Inject a sequence of keyboard, mouse, and wheel events. Events with t > 0 are scheduled via the PIC timer for cycle-accurate delivery.

Request

{
    "events": [
        {"t": 0, "type": "key", "key": "KBD_enter", "pressed": true},
        {"t": 50, "type": "key", "key": "KBD_enter", "pressed": false},
        {"type": "mouse_move", "x_rel": 5.0, "y_rel": -3.0},
        {"type": "mouse_button", "button": "left", "pressed": true},
        {"type": "mouse_wheel", "delta": 1.0}
    ]
}

Response

{"status": "ok", "events_scheduled": 5}

Key names: KBD_a–KBD_z, KBD_0–KBD_9, KBD_f1–KBD_f12, KBD_enter, KBD_space, KBD_esc, KBD_tab, KBD_backspace, KBD_up, KBD_down, KBD_left, KBD_right, and all modifier/special keys.

Button names: left, right, middle.

Returns 400 for unknown key names, event types, or button names.

POST /api/v1/input/record/start

Start recording all keyboard and mouse input. Returns 409 if already recording.

POST /api/v1/input/record/pause

Toggle pause on the active recording. Returns 409 if not recording.

POST /api/v1/input/record/stop

Stop recording and return all captured events. The returned events can be replayed via /input/sequence.

{
    "event_count": 42,
    "duration_ms": 5234.5,
    "events": [
        {"t": 0.0, "type": "key", "key": "KBD_a", "pressed": true},
        ...
    ]
}

Returns 409 if not recording.

GET /api/v1/input/record/status

Query recording state.

{
    "recording": true,
    "paused": false,
    "event_count": 42,
    "duration_ms": 5234.5
}

GET /api/v1/video/frame

Capture the current video frame.

Query parameters:

• format: jpeg (default), png, or raw
• quality: 1–100 (JPEG only, default 98)

Also respects the Accept header: image/png or application/octet-stream.

Returns 503 if no frame has been rendered yet.

The raw format contains a binary header: uint32 width, uint32 height, int32 pitch, uint8 pixel_format, uint16 palette_count, followed by palette data (if paletted) and image data.

GET /api/v1/video/frame/info

Frame metadata without image data.

{
    "width": 720,
    "height": 400,
    "pixel_format": "BGRX32_ByteArray",
    "pitch": 2880,
    "is_paletted": false
}

POST /api/v1/drive/swap

Mount or swap a floppy or hard disk image on a drive letter. For multi-disk game installations, call this when the installer prompts for the next disk. A relative image path resolves against the conf anchor, then each configured image root; the first existing file wins. Scripts can do the same in-process with dosbox.drive_swap().

Request

{
    "drive": "A",
    "image": "/path/to/disk2.img"
}

Returns 400 for missing fields, invalid drive letters, or files that do not exist.

GET /api/v1/cpu/state

Read all CPU registers.

GET /api/v1/memory/:offset/:len

GET /api/v1/memory/:segment/:offset/:len

Read memory from the given address.

The optional segment parameter can be the name of a segment register or a number. All URL parameters accept hex strings if prefixed with 0x.

By default this outputs the raw binary data; set Accept: application/json to request a JSON response with the data encoded in Base64.

PUT /api/v1/memory/:offset

PUT /api/v1/memory/:segment/:offset

Write memory to the given address.

Path parameters work the same as for GET.

Accepts either raw binary data with Content-Type: application/octet-stream or a JSON object with a Base64 encoded field data with Content-Type: application/json.

The If-Match header can be set to Base64 encoded data to perform an atomic compare-and-swap operation.

Returns 412 (Precondition Failed) if the current data does not match the If-Match header.

POST /api/v1/memory/allocate

Allocate memory.

Request

{
    "size": size_bytes,
    "area": "CONV"|"UMA"|"XMS",
    "strategy": "BEST_FIT"|"FIRST_FIT"|"LAST_FIT"
}

Response

{"addr": physical_address}

The XMS allocator only supports BEST_FIT.

POST /api/v1/memory/free

Free allocated memory at the given address.

{"addr": physical_address}

Returns 400 on invalid addresses.

GET /api/v1/dos/internals

Pointers to internal DOS data structures (list of lists, DOS swappable area, first shell).