api: add x-continuum-heads to writes

1 files changed, 18 insertions, 1 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index fac802d..0aea4a6 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -169,12 +169,18 @@ paths:
       responses:
         '200':
           description: With `increment`, the counter's value after it.
+          headers:
+            x-continuum-heads:
+              $ref: '#/components/headers/WrittenHeads'
           content:
             application/json:
               schema:
                 type: integer
         '201':
           description: Inserted, and where.
+          headers:
+            x-continuum-heads:
+              $ref: '#/components/headers/WrittenHeads'
           content:
             application/json:
               schema:
@@ -215,6 +221,9 @@ paths:
       responses:
         '204':
           description: Deleted.
+          headers:
+            x-continuum-heads:
+              $ref: '#/components/headers/WrittenHeads'
         '400':
           description: Invalid path.
         '401':
@@ -1301,6 +1310,14 @@ components:
         type: string
         format: uuid
 
+  headers:
+    WrittenHeads:
+      description: >-
+        The document's heads after the write (sorted hex, comma-separated): a read with
+        them (`at`) on any node that has them includes the write.
+      schema:
+        type: string
+
   responses:
     Unauthorized:
       description: Missing or wrong credentials.
@@ -1316,7 +1333,7 @@ components:
       description: The value.
       headers:
         x-continuum-heads:
-          description: With `heads=true`, the heads at the time of the read (sorted hex, comma-separated).
+          description: With `heads=true`, the heads at the time of the read (sorted hex, comma-separated); on a write, those after it (`WrittenHeads`).
           schema:
             type: string
         x-continuum-stale: