DOSBox Staging API

Welcome to the DOSBox REST API. This embedded webserver exposes REST endpoints to access the internal state of the emulated machine and control DOSBox Staging remotely.

All endpoints access the internal state atomically between steps of the emulated CPU. They will never be executed during natively implemented DOS functions or interrupts — this means the internal data structures are guaranteed to be consistent in any given snapshot.

NOTE: This feature has been primarily tested with core = normal running 16-bit real-mode applications at the moment. Your experience with other CPU modes and different memory models may vary.

GET /api/v1/cpu/state

Read the state of the CPU. Returns the values of 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.

This accept 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. The length of this comparison data can be different from the written data.

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
}

conv and UMA allocate memory from DOS. XMS allocates raw pages and marks them as reserved for EMS and XMS.

strategy controls the allocator behavior, the default is best_fit which is almost always the best setting. The other options will prefer lower/higer addresses in the selected area.

The XMS allocator only supports best_fit.

POST /api/v1/memory/free

Frees allocated memory at the given address.

Request

{
    "addr": physical_address,
}

Returns 400 on invalid addresses.

GET /api/v1/dos/internals

Retrieve pointers to internal DOS data structures like the DOS swappable area and list of lists.

GET /api/v1/dosbox/info

Retrieve DOSBox version and relevant paths.