# 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.

For example, api/v1/memory/0/0x100000 downloads a snapshot of the entire lower memory area.

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.

## POST /api/v1/dosbox/shutdown

Request a graceful shutdown of DOSBox Staging.