taler-docs

commit bf64ca8d9c38ab08d24413e0a76575cf0814847b
parent 8e7245c57ac5f31374103a0298ddbe22e2acf20f
Author: Iván Ávalos <avalos@disroot.org>
Date:   Sat,  8 Aug 2026 01:11:48 +0200

dd92: document GET /backups/$ACCOUNT_KEY for account status

Diffstat:
M
design-documents/092-incremental-backup-sync.rst
 | 
36
++++++++++++++++++++++++++++++++++++

1 file changed, 36 insertions(+), 0 deletions(-)
diff --git a/design-documents/092-incremental-backup-sync.rst b/design-documents/092-incremental-backup-sync.rst
@@ -316,6 +316,42 @@ hash.
    both blocks and objects; exceeding it yields ``413``.  ``version``
    follows the Taler ``current:revision:age`` convention.
 
+.. http:get:: /backups/${ACCOUNT_KEY}
+
+   Report the state of the account: when it expires, and how much of the
+   storage allowance its backup uses.  Requires no signature, like the
+   other read endpoints -- the account public key is the capability, and
+   the stored data is client-encrypted.
+
+   This is the only endpoint that answers for an expired account rather
+   than demanding payment: when the account expires is precisely what
+   the caller is asking, so a ``402`` here would be useless.  Wallets
+   use it to tell the user how long the backup is paid for without
+   waiting for the next write to fail.
+
+   **Response**
+
+   :http:statuscode:`200 OK`:
+     The body is a `SyncAccountStatus` object.  Returned even when
+     ``expiration_date`` lies in the past.
+   :http:statuscode:`404 Not found`:
+     The server does not know this account at all.  It has never been
+     paid for, so there is no expiry to report.
+
+   .. ts:def:: SyncAccountStatus
+
+      interface SyncAccountStatus {
+        // When the account expires, or expired.  Every other endpoint
+        // answers 402 past this point.
+        expiration_date: Timestamp;
+
+        // Total size of the account's stored blocks, in bytes.
+        storage_used_bytes: number;
+
+        // Number of blocks in the account's linked list.
+        block_count: number;
+      }
+
 .. http:get:: /backups/${ACCOUNT_KEY}/blocks
 
    List blocks from the account's linked list with pagination.