Vector HTTP API

Generated automatically from src/common/backend.py. Use this page as the landing pad for connectivity guides and endpoint documentation.

Quick links

Connectivity guides

Routes & endpoints

Jump directly to a handler. Links open source on GitHub with accurate line numbers.

/api/auth/challenge
/api/auth/password_check
/api/game/reboot
/api/game/name
/api/game/active_config
/api/game/configs_list
/api/game/status
/api/leaders
/api/score/delete
/api/tournament
/api/leaders/reset
/api/tournament/reset
/api/scores/claimable
/api/scores/claim
/api/players
/api/player/update
/api/player/scores
/api/personal/bests
/api/player/scores/reset
/api/adjustments/status
/api/adjustments/name
/api/adjustments/capture
/api/adjustments/restore
/api/settings/get_claim_methods
/api/settings/set_claim_methods
/api/settings/get_tournament_mode
/api/settings/set_tournament_mode
/api/settings/get_show_ip
/api/settings/set_show_ip
/api/time/midnight_madness_available
/api/time/get_midnight_madness
/api/time/set_midnight_madness
/api/time/trigger_midnight_madness
/api/settings/factory_reset
/api/settings/reboot
/api/last_ip
/api/available_ssids
/api/network/peers
/api/set_date
/api/get_date
/api/version
/api/fault
/api/export/scores
/api/import/scores
/api/memory-snapshot
/api/logs
/api/formats/available
/api/formats/set
/api/formats/active
/api/diagnostics/switches
/api/update/check
/api/update/apply
/api/in_ap_mode
/api/in_ap_mode
/api/settings/set_vector_config

`/api/auth/challenge`

Handler: get_challenge

Request a new authentication challenge

Request

No parameters inferred.

Response

Status codes

200 - Challenge issued
429 - Too many active challenges

Response body: JSON containing a single challenge token.

{
    "challenge": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

`/api/auth/password_check`

Handler: check_password
Authentication: Required (see Authentication guide).

Convenience method to verify credentials without side effects

Request

No parameters inferred.

Response

Status codes

200 - Credentials accepted
401 - Credentials rejected

Response body: Acknowledgement string

"ok"

`/api/game/reboot`

Handler: app_reboot_game
Authentication: Required (see Authentication guide).

Power-cycle the pinball machine and restart the scheduled tasks

Request

No parameters inferred.

Response

Status codes

200 - Reboot triggered

Response body: Empty body; returns OK on success

"ok"

`/api/game/name`

Handler: app_game_name

Get the human-friendly title of the active game configuration

Request

No parameters inferred.

Response

Status codes

200 - Active game returned

Response body: Plain-text game name

"Attack from Mars"

`/api/game/active_config`

Handler: app_game_config_filename

Get the filename of the active game configuration. Note that on EM systems this is the same as the game name.

Request

No parameters inferred.

Response

Status codes

200 - Active configuration returned

Response body: JSON object identifying the configuration file in use

{
    "active_config": "AttackMars_11"
}

`/api/game/configs_list`

Handler: app_game_configs_list

List all available game configuration files

Request

No parameters inferred.

Response

Status codes

200 - Configurations listed

Response body: Mapping of configuration filenames to human-readable titles

{"F14_L1": {"name": "F14 Tomcat", "rom": "L1"}, "Taxi_L4": {"name": "Taxi", "rom": "L4"}}
        {
            "F14_L1": {
                "name": "F14 Tomcat",
                "rom": "L1"
            },
            "Taxi_L4": {
                "name": "Taxi",
                "rom": "L4"
            }
        }

`/api/game/status`

Handler: app_game_status

Retrieve the current game status such as ball in play, scores, and anything else the configured game supports

Request

No parameters inferred.

Response

Status codes

200 - Status returned

Response body: JSON object describing current play state, score, and timers

{
    "GameActive": true,
    "BallInPlay": 2,
    "Scores": [1000, 0, 0, 0]
}

`/api/leaders`

Handler: app_leaderBoardRead

Fetch the main leaderboard

Request

No parameters inferred.

Response

Status codes

200 - Leaderboard returned

Response body: Sorted list of leaderboard entries with rank and relative times

[
    {
        "initials": "ABC",
        "score": 123456,
        "rank": 1,
        "ago": "2h"
    }
]

`/api/score/delete`

Handler: app_scoreDelete
Authentication: Required (see Authentication guide).

Delete one or more score entries from a leaderboard

Request

Body parameters

delete list required - Collection of score objects containing score and initials.
list string required - Target list name (e.g. leaders or tournament)

Response

Status codes

200 - Scores removed

Response body: Confirmation indicator

{"success": true}

`/api/tournament`

Handler: app_tournamentRead

Read the tournament leaderboard

Request

No parameters inferred.

Response

Status codes

200 - Tournament leaderboard returned

Response body: List of tournament scores sorted by game order

[
    {
        "initials": "ABC",
        "score": 123456,
        "game": 1
    }
]

`/api/leaders/reset`

Handler: app_resetScores
Authentication: Required (see Authentication guide).

Clear the main leaderboard

Request

No parameters inferred.

Response

Status codes

200 - Scores cleared

"ok"

`/api/tournament/reset`

Handler: app_tournamentClear
Authentication: Required (see Authentication guide).

Clear tournament standings and resets the game counter

Request

No parameters inferred.

Response

Status codes

200 - Tournament data cleared

"ok"

`/api/scores/claimable`

Handler: app_getClaimableScores

List recent claimable plays

Request

No parameters inferred.

Response

Status codes

200 - Claimable scores returned

Response body: Collection of unclaimed score records

[
    {
        "score": 12345,
        "player_index": 0,
        "game": 1
    }
]

`/api/scores/claim`

Handler: app_claimScore

Apply initials to an unclaimed score

Request

Body parameters

initials string required - Player initials to record
player_index int required - Player slot or position associated with the score
score int required - Score value to claim

Response

Status codes

200 - Score claimed

"ok"

`/api/players`

Handler: app_getPlayers

List registered players

Request

No parameters inferred.

Response

Status codes

200 - Player list returned

Response body: Mapping of player IDs to initials and names

{
    "0": {
        "initials": "ABC",
        "name": "Alice"
    }
}

`/api/player/update`

Handler: app_updatePlayer
Authentication: Required (see Authentication guide).

Update a stored player record

Request

Body parameters

id int required - Player ID to update
initials string required - Up to three alphabetic characters
full_name string optional - Player display name (truncated to 16 characters)

Response

Status codes

200 - Record updated

"ok"

`/api/player/scores`

Handler: app_getScores

Fetch all scores for a specific player

Request

Body parameters

id int required - Player index to inspect

Response

Status codes

200 - Player scores returned

Response body: Sorted list of score entries with rank, initials, and timestamps

[
    {
        "score": 10000,
        "rank": 1,
        "initials": "ABC",
        "date": "2024-01-01",
        "ago": "1d"
    }
]

`/api/personal/bests`

Handler: app_personal_bests

Return the best score for each registered player

Request

No parameters inferred.

Response

Status codes

200 - Personal bests returned

Response body: Leaderboard of each player's highest score

[
    {
        "player_id": 0,
        "initials": "ABC",
        "score": 12345,
        "rank": 1
    }
]

`/api/player/scores/reset`

Handler: app_resetIndScores
Authentication: Required (see Authentication guide).

Clear all scores for a single player

Request

Query parameters

id int required - Player index whose scores should be erased

Response

Status codes

200 - Scores cleared

"ok"

`/api/adjustments/status`

Handler: app_getAdjustmentStatus

Get the status of each adjustment bank

Request

No parameters inferred.

Response

Status codes

200 - Adjustment metadata returned

Response body: List of adjustment profiles with [Name, Active, Exists], along with a flag indicating overall support

{
    "profiles": [
        ["Free Play", false, true],
        ["Arcade", true, true],
        ["", false, false],
        ["", false, false]
    ],
    "adjustments_support": true
}

`/api/adjustments/name`

Handler: app_setAdjustmentName
Authentication: Required (see Authentication guide).

Set the name of an adjustment profile

Request

Body parameters

index int required - Adjustment slot to rename
name string required - New name for the slot

Response

Status codes

200 - Name updated

"ok"

`/api/adjustments/capture`

Handler: app_captureAdjustments
Authentication: Required (see Authentication guide).

Capture current adjustments into a profile

Request

Body parameters

index int required - Destination profile for captured adjustments

Response

Status codes

200 - Adjustments stored

"ok"

`/api/adjustments/restore`

Handler: app_restoreAdjustments
Authentication: Required (see Authentication guide).
Cooldown: 5s

Restore adjustments from a saved profile

Request

Body parameters

index int required - Adjustment profile to restore

Response

Status codes

200 - Adjustments restored

"ok"

`/api/settings/get_claim_methods`

Handler: app_getScoreCap

Read score entry methods

Request

No parameters inferred.

Response

Status codes

200 - Claim methods returned

Response body: All keys are available methods for entering initials, only enabled methods are true

{
    "on-machine": true,
    "web-ui": false
}

`/api/settings/set_claim_methods`

Handler: app_setScoreCap
Authentication: Required (see Authentication guide).

Configure which score claim methods are enabled

Request

Body parameters

on-machine bool optional - Allow initials entry on the physical game
web-ui bool optional - Allow initials entry via the web interface

Response

Status codes

200 - Preferences updated

"ok"

`/api/settings/get_tournament_mode`

Handler: app_getTournamentMode

Get whether tournament mode is enabled

Request

No parameters inferred.

Response

Status codes

200 - Tournament mode returned

Response body: Flag indicating tournament mode state

{"tournament_mode": true}

`/api/settings/set_tournament_mode`

Handler: app_setTournamentMode
Authentication: Required (see Authentication guide).

Enable or disable tournament mode

Request

Body parameters

tournament_mode bool required - New tournament mode setting

Response

Status codes

200 - Setting saved

"ok"

`/api/settings/get_show_ip`

Handler: app_getShowIP

Check whether the IP address is shown on the display

Request

No parameters inferred.

Response

Status codes

200 - Preference returned

Response body: Flag indicating whether the IP is displayed

{"show_ip": true}

`/api/settings/set_show_ip`

Handler: app_setShowIP
Authentication: Required (see Authentication guide).

Set whether the IP address should be shown on the display

Request

Body parameters

show_ip bool required - Whether to show the IP address on screen

Response

Status codes

200 - Preference updated

"ok"

`/api/time/midnight_madness_available`

Handler: app_midnightMadnessAvailable

Report if Midnight Madness mode is supported

Request

No parameters inferred.

Response

Status codes

200 - Availability returned

Response body: Flag indicating if the game supports Midnight Madness

{"available": true}

`/api/time/get_midnight_madness`

Handler: app_getMidnightMadness

Read Midnight Madness configuration

Request

No parameters inferred.

Response

Status codes

200 - Configuration returned

Response body: Flags describing whether Midnight Madness is enabled and always on

{
    "enabled": true,
    "always": false
}

`/api/time/set_midnight_madness`

Handler: app_setMidnightMadness
Authentication: Required (see Authentication guide).

Set Midnight Madness configuration

Request

Body parameters

always bool required - Keep Midnight Madness enabled for all games
enabled bool required - Enable timed Midnight Madness events

Response

Status codes

200 - Configuration saved

"ok"

`/api/time/trigger_midnight_madness`

Handler: app_triggerMidnightMadness

Immediately trigger Midnight Madness

Request

No parameters inferred.

Response

Status codes

200 - Event triggered

"ok"

`/api/settings/factory_reset`

Handler: app_factoryReset
Authentication: Required (see Authentication guide).

Perform a full factory reset of Vector and the pinball machine

Request

No parameters inferred.

Response

Status codes

200 - Reset initiated

"ok"

`/api/settings/reboot`

Handler: app_reboot
Authentication: Required (see Authentication guide).

Reboot the Pinball machine

Request

No parameters inferred.

Response

Status codes

200 - Reboot initiated

"ok"

`/api/last_ip`

Handler: app_getLastIP

Get the last known IP address

Request

No parameters inferred.

Response

Status codes

200 - IP returned

Response body: Last recorded IP address

{"ip": "192.168.0.10"}

`/api/available_ssids`

Handler: app_getAvailableSSIDs

Scan for nearby Wi-Fi networks

Request

No parameters inferred.

Response

Status codes

200 - Networks listed

Response body: Array of SSID records with signal quality and configuration flag

[
    {
        "ssid": "MyNetwork",
        "rssi": -40,
        "configured": true
    }
]

`/api/network/peers`

Handler: app_getPeers

List other vector devices discovered on the local network

Request

No parameters inferred.

Response

Status codes

200 - Peer map returned

Response body: Mapping of peer identifiers to network information

{
    "192.168.4.243": {
        "name": "Pinbot",
        "self": true
    }
}

`/api/set_date`

Handler: app_setDateTime
Authentication: Required (see Authentication guide).

Set Vector's date and time

Request

Body parameters

date list required - RTC tuple [year, month, day, hour, minute, second]

Response

Status codes

200 - Clock updated

"ok"

`/api/get_date`

Handler: app_getDateTime

Read the current time according to Vector

Request

No parameters inferred.

Response

Status codes

200 - RTC timestamp returned

Response body: Tuple containing RTC date/time fields

{"date": [2024, 1, 1, 0, 12, 0, 0]}

`/api/version`

Handler: app_version

Get the software version. Note: this is the version for the target hardware (what the user sees) and not the release version.

Request

No parameters inferred.

Response

Status codes

200 - Version returned

Response body: Current firmware version string

{"version": "1.0.0"}

`/api/fault`

Handler: app_install_fault

Get the list of currently active faults

Request

No parameters inferred.

Response

Status codes

200 - Faults returned

Response body: Collection of fault flags and details

{"faults": []}

`/api/export/scores`

Handler: app_export_leaderboard

Export all leaderboard data

Request

No parameters inferred.

Response

Status codes

200 - Leaderboard export file returned

{
        "scores": {"tournament": [{"initials": "AAA", "score": 938479, "index": 2, "game": 0}],
        "leaders": [{"initials": "MSM", "date": "02/04/2025", "full_name": "Maxwell Mullin", "score": 2817420816}]},
        "version": 1

`/api/import/scores`

Handler: app_import_leaderboard
Authentication: Required (see Authentication guide).

Import leaderboard data from an uploaded file

Request

Body parameters

file bytes required - Score export file content

Response

Status codes

200 - Import completed

Response body: Success indicator

{"success": true}

`/api/memory-snapshot`

Handler: app_memory_snapshot

Stream a snapshot of memory contents

Request

No parameters inferred.

Response

Status codes

200 - Snapshot streaming

Response body: Text stream of byte values

`/api/logs`

Handler: app_getLogs
Authentication: Required (see Authentication guide).
Cooldown: 10s
Single instance: Yes

Download the system log file

Request

No parameters inferred.

Response

Status codes

200 - Log download streaming

Response body: Log file content

`/api/formats/available`

Handler: app_list_available_formats

Get the list of available game formats

Request

No parameters inferred.

Response

Status codes

200 - Formats returned

Response body: Collection of available game formats with metadata and configuration options

[
    {
        "id": 0,
        "name": "Arcade",
        "description": "Manufacturer standard game play"
    }
]

`/api/formats/set`

Handler: app_set_current_format
Authentication: Required (see Authentication guide).

Set the active game format

Request

Body parameters

format_id int required - Format identifier to activate
options dict optional - Configuration options for the selected format

Response

Status codes

200 - Format set successfully

`/api/formats/active`

Handler: app_get_active_formats

Get the currently active game format

Request

No parameters inferred.

Response

No structured response documented.

`/api/diagnostics/switches`

Handler: app_get_switch_diagnostics

Get diagnostic information for all switches

Request

No parameters inferred.

Response

No structured response documented.

`/api/update/check`

Handler: app_updates_available
Cooldown: 10s

Get the metadata for the latest available software version. This does not download or apply the update.

Request

No parameters inferred.

Response

Status codes

200 - Update metadata returned

Response body: JSON payload describing available updates

{
    "release_page": "https://github.com/...",
    "notes": "Another Great Release! Here's what we changed",
    "published_at": "2025-12-30T17:54:49+00:00",
    "url": "https://github.com/...",
    "version": "1.9.0"
}

`/api/update/apply`

Handler: app_apply_update
Authentication: Required (see Authentication guide).

Download and apply a software update from the provided URL.

Request

Body parameters

url string required - Signed update package URL
skip_signature_check bool optional - Bypass signature validation (for developer builds)

Response

Status codes

200 - Streaming progress updates

Response body: Sequence of JSON log entries with log and percent fields

{
    "log": "Starting update",
    "percent": 0
}

`/api/in_ap_mode`

Handler: app_inAPMode

Indicates if Vector is running in AP or app mode

Request

No parameters inferred.

Response

Status codes

200 - Mode reported

Response body: Flag showing AP mode status

{"in_ap_mode": false}

`/api/in_ap_mode`

Handler: app_inAPMode

No description provided.

Request

No parameters inferred.

Response

No structured response documented.

`/api/settings/set_vector_config`

Handler: app_setWifi

[AP Mode Only] Configure Wi-Fi credentials and default game

Request

Body parameters

ssid string required - Wi-Fi network name
wifi_password string required - Wi-Fi network password
vector_password string required - Password for authenticated API access
game_config_filename string required - Game configuration filename to load

Response

Status codes

200 - Configuration saved

"ok"