chore: add documentation for paging caveats (#422)

`store/list` and `upload/list` both accept paging parameters - document them.
storacha · Feb 7, 2023 · a68afd2 · a68afd2
1 parent 5cfe274
commit a68afd2
Showing 1 changed file with 14 additions and 2 deletions.
diff --git a/spec/capabilities.md b/spec/capabilities.md
@@ -197,7 +197,13 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 #### Caveats
 
-None currently, but this is expected to change once pagination is fully implemented.
+`cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `store/list`
+`size` can be set to change the number of items returned by an `store/list` invocation
+
+| field       | value                    | required? | context                                                         |
+| ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
+| `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
+| `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
 
 ## `upload/` namespace
 
@@ -278,7 +284,13 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 #### Caveats
 
-None currently, but this is expected to change once pagination is fully implemented.
+`cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `upload/list`
+`size` can be set to change the number of items returned by an `upload/list` invocation
+
+| field       | value                    | required? | context                                                         |
+| ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
+| `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
+| `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
 
 ## `voucher/` namespace