Everything the official agent does — pushing a save up, pulling the newest one back down — it does through a public HTTP API. That API is open to you as well: if you play on a machine the agent does not cover (a Linux box, a Steam Deck, a NAS that holds your saves), you can write your own client and it will be a first-class citizen.
Getting a token
A client authenticates with an API token, which you create on the Devices page — one per machine, named, and revocable on its own without touching the others. The token is shown once, at creation: grailward stores only a digest of it and cannot show it to you again. Lost it? Revoke it and create another.
The reference
The full reference lives at /docs/api: every endpoint, field and error, plus a curl command you can paste to check that your token works. The same document is published as a machine-readable OpenAPI spec at /api/v1/openapi.yaml, ready to feed to a client generator. Both are in English — they are written for developers.
What your client can do
- Upload a character (
.d2s) or a shared stash (.d2i). An upload is never refused: there is no character lock, and two machines pushing the same character is fine — you decide later which save wins. - Ask what the server currently holds, and download anything that is newer than your local copy.
- Sync the map-reveal files (
.map,.ma0…) that remember the map you have explored.
Sending the same save twice is safe: grailward identifies a save by its content, so a repeated upload stores nothing new.