Feed API

What a game client module sends and receives. Every call but the first carries the token from pairing:

Authorization: Bearer <token>

Base address: http://127.0.0.1:8090/api/v1. The machine-readable description is at openapi.json.

POST/api/v1/pair

Ask for a pairing code Call it once, when the module has no token yet. Show the code and the link in the game.

No token needed.

Request body

FieldTypeDescription
characterrequiredstringThe character the client playsup to 30 characters
serverstringServer slug or name, for example orion, when a server adapter knows itup to 60 characters
hoststringThe client's login address: the server is found by its domainup to 200 characters
worldstringThe world name the client logged in toup to 60 characters
clientVersionintegerThe client's protocol version, for example 860
platformstringOperating system, for example Windows 11up to 40 characters
modulestringModule name and versionup to 40 characters

Response

FieldTypeDescription
coderequiredstringShow it to the player. It is valid for 15 minutes
urlrequiredstringOpen it to start a guest dashboard, or to add the client to an account
tokenrequiredstringThe client's secret. Store it; it works once the code is used
expiresAtrequiredinteger

POST/api/v1/status

Send the character's state As often as the reply says: every 2 s while someone watches the character, 5 s while Team radar shows it, 30 s otherwise. The reply also says when to send the next capture.

Request body

FieldTypeDescription
schema"vw.status/1"Payload schema and version
modulerequiredstringName and version of the sending module, for example voidwatch-feed/0.5.2up to 40 characters
onlinerequiredbooleanThe character is logged in
characterrequiredCharacter
character.namerequiredstringCharacter nameup to 30 characters
character.vocationstringVocation, for example Elite Knightup to 30 characters
character.levelrequiredinteger≥ 1, ≤ 5000
character.exprequiredintegerTotal experience points≥ 0
posrequiredPosition
pos.xrequiredintegerMap x≥ 0, ≤ 65535
pos.yrequiredintegerMap y≥ 0, ≤ 65535
pos.zrequiredintegerFloor, 0 to 15; 7 is ground level≥ 0, ≤ 15
capintegerFree capacity, in oz≥ 0
staminaintegerStamina, in minutes≥ 0, ≤ 2520
expPerHourintegerExp per hour as the client measures it≥ 0
routestringThe loaded cavebot routeup to 80 characters
routeOnbooleanThe cavebot is running
labelstringThe route label the bot is atup to 40 characters
phase"hunting" | "to_city" | "in_city" | "to_resp" | "parked" | "stopped" | "unknown" | "town" | "at_check" | "leaving"Where the character is in its route, from the labels hunt, refill, city and resp: unknown when a label is missing. town, at_check and leaving come from bot adapters before version 4
labelsMissingstring[]Route parts without a label. check and leave come from bot adapters before version 4up to 4 items
planPlanStateThe bot's plan: a command that acts when the bot reaches a label. An ended plan stays for two minutes
plan.idintegerThe command that started the plan
plan.kindrequired"refill" | "go_depot" | "load_route"
plan.routestringThe route a switch loadsup to 80 characters
plan.staterequired"running" | "done" | "stuck" | "cancelled" | "taken_over" | "failed"
plan.step"hunt" | "city" | "depot" | "switch"What the running plan waits for
plan.messagestringup to 200 characters
plan.sinceintegerUnix seconds when the plan started
plan.untilintegerUnix seconds when the waiting step gives up as stuck
plan.endedintegerUnix seconds when the plan ended
routesstring[]Every route the bot can loadup to 100 items
suppliesSupplyItem[]up to 60 items
supplies[].namerequiredstringItem name, as the game writes itup to 60 characters
supplies[].haverequiredintegerHow many the character carries, closed bags included where the game said≥ 0
supplies[].wantintegerHow many the bot keeps in stock; missing when the list comes from the use lines≥ 0
suppliesSourcestringbot: the bot's own supply list; used: every item the game's use lines namedup to 20 characters
tasksTaskItem[]up to 10 items
tasks[].namerequiredstringItem or creature name, as the game writes itup to 60 characters
tasks[].haverequiredintegerHow many the character has now≥ 0
tasks[].wantrequiredintegerHow many the bot keeps in stock, or the task goal≥ 0
tasks[].expintegerExp reward for the goal, if the server says≥ 0
tasks[].taskPointsintegerTask points for the goal, if the server has them≥ 0
taskPointsintegerThe task points balance, on servers with task points≥ 0
taskWeekTaskWeekTask points this week, on servers with a weekly cap
taskWeek.earnedrequiredintegerTask points earned this week≥ 0
taskWeek.caprequiredintegerThe most task points a week allows≥ 0
lootLootItem[]up to 200 items
loot[].namerequiredstringItem nameup to 60 characters
loot[].countrequiredintegerLooted since the session started≥ 0
loot[].sellintegerNPC price per item, if the module knows it. The server fills it in otherwise≥ 0
usedUsedItem[]Supplies used since the loot counter startedup to 200 items
used[].namerequiredstringItem nameup to 60 characters
used[].countrequiredintegerUsed since the counter started≥ 0
used[].buyintegerNPC buy price per item, if the module knows it≥ 0
lootHoursnumberHours since the loot counter started≥ 0
lootSourcestringWhere the loot count comes from: corpse, the loot messages every server sends, or the id of an adapter such as an autolootup to 40 characters
skullsSkull[]Skulled players in viewup to 20 items
skulls[].namerequiredstringPlayer nameup to 30 characters
skulls[].skullrequired"white" | "red" | "black" | "yellow" | "green" | "orange"Skull colour
skulls[].distintegerSquares away from the character≥ 0, ≤ 100
blessedbooleanOnly on servers with blessings
pzbooleanThe character stands in a protection zone
pzLockbooleanThe character is PZ locked: it cannot enter a protection zone
outfitOutfitThe character's look, drawn on the map
outfit.typerequiredintegerThe look type≥ 0, ≤ 10000
outfit.headinteger≥ 0, ≤ 255
outfit.bodyinteger≥ 0, ≤ 255
outfit.legsinteger≥ 0, ≤ 255
outfit.feetinteger≥ 0, ≤ 255
outfit.addonsinteger≥ 0, ≤ 3
skull"white" | "red" | "black" | "yellow" | "green" | "orange"The character's own skull, if it has one
playersInViewintegerOther players in view≥ 0, ≤ 500
redemptionbooleanOnly on servers with death redemption: it is active now
redemptionLeftintegerOnly on servers with redemption≥ 0
targetOnbooleanThe targeting bot is running
botConfigstringThe bot preset, for example vBot_4.8up to 60 characters
targetProfilestringThe loaded targeting profileup to 80 characters
botProfileintegerThe bot settings profile, for example vBot's 1 to 5≥ 1, ≤ 20
adaptersAdapterState[]The adapters the module runs, and whether each is onup to 30 items
adapters[].idrequiredstringAdapter id, for example orion-ots-tasks or botup to 40 characters
adapters[].versionstringup to 20 characters
adapters[].onrequiredbooleanFalse: the adapter stopped after errors, or the bot stopped attaching
adapters[].wantstringFor the bot adapter: the version the module ships. A lower version waits for a bot reloadup to 20 characters
addonsAddonState[]The addons in the data folder, and whether each runsup to 30 items
addons[].idrequiredstringAddon id, for example exiva-map
addons[].versionstringThe module version the addon came withup to 20 characters
addons[].onrequiredbooleanLoaded now
addons[].errorstringWhy it is not loaded: installing, the download failed, or its last errorup to 200 characters
featuresstring[]What the module runs, for example status, captures and commands. The dashboard turns off what is not listed. Left out: everythingup to 20 items
actionsstring[]The command actions this client can run now, for example toggle_cavebot. The dashboard offers only theseup to 40 items
settingsChangeobjectA change from the Settings tab of the Voidwatch window: {rev, values}. The values follow the rules of the Clients page. A bad value never refuses the status: settingsSaved in the reply says why

Response

FieldTypeDescription
okrequiredboolean
statusEveryrequiredintegerSeconds until the next status: 2 while someone watches the character, 5 while Team radar shows it, 30 otherwise
captureEveryrequiredintegerSeconds until the next capture: short while someone watches or an alert fired
commandsrequiredintegerCommands waiting; fetch them from /api/v1/commands
settingsSettingsThe player's module settings, for example minimap: true
latestModulestringThe newest module release on GitHub, as the server last saw it. The upload script offers an update only when this is higher than the running version
needMapbooleanTrue when the player has no map of this server: send every minimap file again
addonCatalogobject[]The addons of the newest release, for the Voidwatch window: id, name, about, points, plan, size in bytes and version
settingsSavedobjectOnly after a status with settingsChange: {rev, ok, error}. The module keeps sending the change until this names its rev
radarRadarMark[]Only while the client runs the Team radar addon: the player's other characters online on this server, and the guild mates who share their position
radar[].namerequiredstring
radar[].xrequiredinteger
radar[].yrequiredinteger
radar[].zrequiredinteger
radar[].kindrequired"own" | "guild"own: another character of the player. guild: a guild mate who shares their position
atrequiredintegerServer time of this reply, Unix seconds. The reply changes with every send, so the module sees when the upload script last got an answer

GET/api/v1/wait

Wait for a change A long poll: the answer comes the moment someone opens the character on the dashboard, an alert fires or a command is sent, or after `timeout` seconds (at most 25). Keep one open while the client runs, so it switches to the fast pace within a second and costs no requests while nothing happens. A revoke ends it with 401 at once.

Response

FieldTypeDescription
wakerequiredbooleanTrue when something changed before the timeout
statusEveryrequiredinteger
captureEveryrequiredinteger
commandsrequiredinteger

GET/api/v1/wake

Ask whether to send the status now A cheap check from memory for clients with Team exiva on. Ask every 2 seconds instead of keeping a long poll open, so the files to send never wait. `wake` is true when a command waits, or when the client should report faster than now, for example because someone opened the character: send the status at once, and its reply brings the commands and the new pace.

Response

FieldTypeDescription
wakerequiredbooleanSend the status now: a command waits, or someone opened the character

POST/api/v1/minimap

Send the minimap file One minimap file of the client, any minimap*.otmm as it is on disk, at most 40 MB, with its change time in X-File-Mtime. It merges into the player's own map of the server: new areas are added, and a tile the file has not seen never covers one the map has. Send each file when it changed and the reply's settings say minimap: true; send all of them again when the reply says needMap: true. At most 30 files per hour for one player and server; more get 429.

Request body

application/octet-stream

Response

any

POST/api/v1/capture

Send a screenshot The game window as JPEG or PNG, at most 2 MB. Send one when /status says so.

Request body

image/jpeg, image/png

Response

any

GET/api/v1/commands

Fetch waiting commands Commands the player sent from the dashboard, oldest first. Fetching marks them as sent. A command older than 60 seconds is not delivered: it shows as expired.

Response

Command[]

POST/api/v1/commands/{cid}/result

Report how a command went

Request body

FieldTypeDescription
okrequiredboolean
messagestringShown in the command logup to 200 characters
dataExivaResultcast_exiva: the parsed answer and where the caster stood
data.bandrequired"beside" | "close" | "far" | "veryfar"next to you, under 100 squares, under 274, or beyond
data.dir"north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west"Left out for next to you
data.levelrequired"same" | "higher" | "lower" | "unknown"The floor: only next to you and close answers name it
data.xrequiredintegerWhere the caster stood when it cast≥ 0, ≤ 65535
data.yrequiredinteger≥ 0, ≤ 65535
data.zrequiredinteger≥ 0, ≤ 15

Response

any

POST/api/v1/exiva

Start a team exiva from a cast in the game The player cast exiva in the game and got an answer. Every character of the team with Team exiva on casts on the same target; the result comes back as an exiva_show command. A second cast on the same target within 10 s joins the run.

Request body

FieldTypeDescription
bandrequired"beside" | "close" | "far" | "veryfar"next to you, under 100 squares, under 274, or beyond
dir"north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west"Left out for next to you
levelrequired"same" | "higher" | "lower" | "unknown"The floor: only next to you and close answers name it
targetrequiredstringThe name the game answered aboutup to 30 characters
posrequiredPositionWhere the character stood when it cast
pos.xrequiredintegerMap x≥ 0, ≤ 65535
pos.yrequiredintegerMap y≥ 0, ≤ 65535
pos.zrequiredintegerFloor, 0 to 15; 7 is ground level≥ 0, ≤ 15
textstringThe game messageup to 120 characters

Response

any

Errors

A payload that does not match the schema gets status 422 with every problem listed:

{
  "error": "invalid payload",
  "problems": [
    {
      "field": "pos.z",
      "message": "Input should be less than or equal to 15"
    }
  ],
  "schema": "/developers/schema"
}

Status 401 means the token is unknown or the player revoked the client. Pair again to get a new one.