grailward API

Manifest of everything the account currently holds

Authorization: Bearer <api_token> 30 requests / 10 minutes · per token

Responses

• 200

  The manifest. An account with nothing in it returns two empty arrays, not an error.

  Field	Type	Description
  characters	array of object	One entry per character that has a current save, sorted by name. A character whose saves were all archived with set_current: false has no current save and does not appear here.
  name	string
  filename	string	The name the save has on disk — <name>.d2s.
  sha256	string	sha256 of the current save's bytes. This is the whole sync protocol: compare it with the sha256 of your local file. Equal means in sync — do nothing.
  size	integer	Size of the current save in bytes.
  synced_at	string (date-time)	ISO 8601, UTC — when the server received this save. Compare against your local file's mtime to decide who is newer when the shas differ.
  source_machine	string | null	The source_machine the uploading client declared, or null if it declared none.
  download_path	string	Path to the raw save. Use it verbatim — prepend the host, do not rebuild it from the name.
  sidecars	array of object	The character's map-reveal sidecars. Always present; an empty array when there are none. Same sha-comparison protocol as the save itself.
  filename	string
  sha256	string	Lowercase hex sha256.
  size	integer
  sidecars_download_path	string	Path to the sidecar batch. Use it verbatim. Always present, even with no sidecars.
  shared_stashes	array of object	One entry per shared stash that has a current save, sorted by (mode, variant).
  mode	string softcore · hardcore
  variant	string modern · legacy
  filename	string	The name this stash has on disk. Send this exact string back as filename on POST /api/v1/snapshots and the upload lands on this same stash — the round-trip is guaranteed by construction.
  size	integer
  sha256	string	Lowercase hex sha256.
  synced_at	string (date-time)
  source_machine	string | null
  download_path	string	Path to the raw .d2i. Use it verbatim.

  One character (with map sidecars) and one shared stash

  {
    "characters": [
      {
        "name": "Kristan",
        "filename": "Kristan.d2s",
        "sha256": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
        "size": 8447,
        "synced_at": "2026-07-13T18:04:21Z",
        "source_machine": "windows-pc",
        "download_path": "/api/v1/characters/Kristan/current",
        "sidecars": [
          {
            "filename": "Kristan.ma0",
            "sha256": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
            "size": 4096
          },
          {
            "filename": "Kristan.map",
            "sha256": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35",
            "size": 3
          }
        ],
        "sidecars_download_path": "/api/v1/characters/Kristan/sidecars"
      }
    ],
    "shared_stashes": [
      {
        "mode": "softcore",
        "variant": "modern",
        "filename": "ModernSharedStashSoftCoreV2.d2i",
        "size": 27231,
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "synced_at": "2026-07-13T18:04:22Z",
        "source_machine": "windows-pc",
        "download_path": "/api/v1/stash/softcore/modern/current"
      }
    ]
  }

  A brand-new account

  {
    "characters": [],
    "shared_stashes": []
  }

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Downloads are paused server-side (feature flag api_download), which covers the manifest as well as the raw-bytes endpoints. Retry later with backoff.

  {
    "error": "Downloads are temporarily disabled — try again later"
  }

Upload a save file

Authorization: Bearer <api_token> 60 requests / 10 minutes · per token

Request body application/json

{
  "raw_base64": "AAAAVwYAAABrAAAA…",
  "sha256": "9f2c1b0e5a7d4c3f8e6b2a1d0c9f8e7d6c5b4a39281706f5e4d3c2b1a0987654",
  "source_machine": "windows-pc"
}

{
  "raw_base64": "VlNTSgABAAA…",
  "sha256": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
  "filename": "ModernSharedStashSoftCoreV2.d2i",
  "source_machine": "steam-deck"
}

{
  "raw_base64": "AAAAVwYAAABrAAAA…",
  "sha256": "9f2c1b0e5a7d4c3f8e6b2a1d0c9f8e7d6c5b4a39281706f5e4d3c2b1a0987654",
  "set_current": false
}

Responses

• 201

  Save stored. status is created.

  Character snapshot result

  Field	Type	Description
  status	string created · unchanged	created (HTTP 201) — a new snapshot was written. unchanged (HTTP 200) — this exact sha256 was already in the character's history; nothing was written. Both are success.
  character	object
  name	string
  class	string	The character's class as the parser names it.
  level	integer
  hardcore	boolean
  snapshot	object
  sha256	string	Lowercase hex sha256.
  created_at	string (date-time)	When the snapshot was stored. On unchanged this is the timestamp of the existing snapshot — the first time these bytes arrived — not of your request.
  item_count	integer	How many items the parser found in the save. A cheap sanity check for your client.

  Shared stash snapshot result

  Field	Type	Description
  status	string created · unchanged
  shared_stash	object
  mode	string softcore · hardcore
  variant	string modern · legacy
  gold	integer
  tab_count	integer
  item_count	integer
  snapshot	object
  sha256	string	Lowercase hex sha256.
  created_at	string (date-time)

• 200

  Save already known (same sha256). status is unchanged, nothing was written, and the returned snapshot is the one already on file. This is the response a retry gets.

  Character snapshot result

  Field	Type	Description
  status	string created · unchanged	created (HTTP 201) — a new snapshot was written. unchanged (HTTP 200) — this exact sha256 was already in the character's history; nothing was written. Both are success.
  character	object
  name	string
  class	string	The character's class as the parser names it.
  level	integer
  hardcore	boolean
  snapshot	object
  sha256	string	Lowercase hex sha256.
  created_at	string (date-time)	When the snapshot was stored. On unchanged this is the timestamp of the existing snapshot — the first time these bytes arrived — not of your request.
  item_count	integer	How many items the parser found in the save. A cheap sanity check for your client.

  Shared stash snapshot result

  Field	Type	Description
  status	string created · unchanged
  shared_stash	object
  mode	string softcore · hardcore
  variant	string modern · legacy
  gold	integer
  tab_count	integer
  item_count	integer
  snapshot	object
  sha256	string	Lowercase hex sha256.
  created_at	string (date-time)

• 400

  raw_base64 missing, or not valid base64.

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 413

  The decoded save is larger than 4 MB — the ceiling for any single save (real .d2s files are tens of KB; .d2i files stay well under a megabyte). Enforced twice: once on Content-Length before decoding, once on the decoded bytes.

• 422

  The bytes could not be ingested. This is never a refusal of a valid save — it means the payload is unreadable or unidentifiable. Branch on status, not on the message.

  The sha256 you claimed is not the sha256 of the bytes you sent

  {
    "status": "checksum_mismatch",
    "error": "the provided sha256 does not match the content"
  }

  Corrupt save, truncated file, or a stash upload with no usable filename

  {
    "status": "invalid_save",
    "error": "filename does not indicate the stash mode (expected SharedStashSoftCoreV2.d2i or SharedStashHardCoreV2.d2i)"
  }

  The bytes are not the kind of save the endpoint routed them to

  {
    "status": "unsupported",
    "error": "this is a character save, not a shared stash"
  }

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Uploads are paused server-side (feature flag api_upload). Nothing is wrong with your request and nothing is wrong with the service — this half of the API is temporarily off. Keep the save and retry later with backoff.

  {
    "error": "Uploads are temporarily disabled — try again later"
  }

Download the character's current save

Authorization: Bearer <api_token> 60 requests / 10 minutes · per token

Path parameters

Responses

• 200

  The raw save file. Write the body to disk byte-for-byte. X-Sha256 lets you verify the transfer, and Content-Disposition carries the filename the game expects.

  Header	Type	Description
  X-Sha256	string	sha256 of the body, lowercase hex — the same value the sync manifest publishes.
  Content-Disposition	string	Always attachment, with the game's filename (e.g. attachment; filename="Kristan.d2s").

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 404

  No such character in your account, or the character exists but has no current save (it was only ever archived with set_current: false). A character belonging to another account is also 404, deliberately — the API never confirms what you cannot reach.

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Downloads are paused server-side (feature flag api_download), which covers the manifest as well as the raw-bytes endpoints. Retry later with backoff.

  {
    "error": "Downloads are temporarily disabled — try again later"
  }

Download a shared stash's current save

Authorization: Bearer <api_token> 60 requests / 10 minutes · per token

Path parameters

Responses

• 200

  The raw save file. Write the body to disk byte-for-byte. X-Sha256 lets you verify the transfer, and Content-Disposition carries the filename the game expects.

  Header	Type	Description
  X-Sha256	string	sha256 of the body, lowercase hex — the same value the sync manifest publishes.
  Content-Disposition	string	Always attachment, with the game's filename (e.g. attachment; filename="Kristan.d2s").

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 404

  No such stash in your account (that mode × variant was never uploaded), or it has no current save. A stash belonging to another account is 404 too.

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Downloads are paused server-side (feature flag api_download), which covers the manifest as well as the raw-bytes endpoints. Retry later with backoff.

  {
    "error": "Downloads are temporarily disabled — try again later"
  }

Download every map-reveal sidecar of a character

Authorization: Bearer <api_token> 60 requests / 10 minutes · per token shares this budget with PUT /api/v1/characters/{name}/sidecars

Path parameters

Responses

• 200

  The character's sidecars, sorted by filename.

  Field	Type	Description
  files	array of object	Every sidecar of the character, sorted by filename. Empty array when there are none.
  filename	string
  sha256	string	Lowercase hex sha256.
  raw_base64	string (byte)	The sidecar's raw bytes, base64-encoded — write them to disk as-is.

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 404

  No character by that name in your account. A character owned by another account answers 404 as well — never 403.

  {
    "error": "Not found"
  }

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Downloads are paused server-side (feature flag api_download), which covers the manifest as well as the raw-bytes endpoints. Retry later with backoff.

  {
    "error": "Downloads are temporarily disabled — try again later"
  }

Upload map-reveal sidecars (batch upsert)

Authorization: Bearer <api_token> 60 requests / 10 minutes · per token shares this budget with GET /api/v1/characters/{name}/sidecars

Path parameters

Request body application/json

{
  "source_machine": "windows-pc",
  "files": [
    {
      "filename": "Kristan.map",
      "sha256": "d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35",
      "raw_base64": "TUFQ"
    },
    {
      "filename": "Kristan.ma0",
      "sha256": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
      "raw_base64": "TUEwREFUQQ=="
    }
  ]
}

Responses

• 200

  The batch was applied — including the empty batch ({"files": []}), which is a no-op. Note this is 200 even when files were created; there is no 201 here.

  Field	Type	Description
  status	string ok	Always ok — a failed batch is a 422, not a 200 with a bad status.
  files	array of object	One entry per file in the request, in the order you sent them.
  filename	string
  status	string created · updated · unchanged	created — first time this file was seen. updated — the content differs and now replaces what was stored (no history is kept). unchanged — same sha256 as what is already stored; nothing was written.

  One new file, one re-sent unchanged

  {
    "status": "ok",
    "files": [
      {
        "filename": "Kristan.map",
        "status": "created"
      },
      {
        "filename": "Kristan.ma0",
        "status": "unchanged"
      }
    ]
  }

• 401

  The Authorization header is missing, malformed, or carries a token that no longer exists (revoked on the Devices page, or the account was deleted).

  {
    "error": "Invalid or missing token"
  }

• 404

  No character by that name in your account. A character owned by another account answers 404 as well — never 403.

  {
    "error": "Not found"
  }

• 413

  The request body is larger than 24 MB (16 files × 1 MB, base64-inflated, plus slack).

• 422

  A file in the batch failed validation, so none of them were written. filename names the offender when the failure can be pinned to one file; it is absent when the batch itself is malformed (not an array, more than 16 files, the same filename twice).

  A name this character cannot have

  {
    "error": "invalid sidecar filename",
    "filename": "Outro.map"
  }

  The declared sha256 does not match the decoded bytes

  {
    "error": "the provided sha256 does not match the content",
    "filename": "Kristan.map"
  }

  More than 16 files in one request

  {
    "error": "too many sidecars in one request (max 16)"
  }

• 429

  Over the rate limit for this token. No Retry-After is sent; wait out the 10-minute window. Failed requests count too — the limiter runs before validation.

  {
    "error": "Too many requests, wait before sending again"
  }

• 503

  Uploads are paused server-side (feature flag api_upload). Nothing is wrong with your request and nothing is wrong with the service — this half of the API is temporarily off. Keep the save and retry later with backoff.

  {
    "error": "Uploads are temporarily disabled — try again later"
  }

This document, machine-readable

Public · no token

Responses

• 200

  The spec.

• 304

  Not modified — your If-None-Match matched the current ETag.