Key-Value REST API

ℹ️ This page is just a rough outline of what I want to cover.

• first added in v0.1.2
• how to start/stop server
• auth token
• how to send requests using curl

Start REST server

• explain auth tokens

$ foks kv rest start
Listening...
Port: 8080

Requests can be sent to http://127.0.0.1:8080.

• --bind-ip 127.0.0.1: specify the IPv4 address where the REST server will listen (default is 127.0.0.1)
• --port 8080: specify the TCP port where the REST server will listen (default is 8080
• --team x: work on behalf of a given team (not necessary?)
• --auth-token xxxxx: clients must supply a matching token (default: none)

Stop REST server

foks kv rest stop

API

• show example of how to include auth token with request

GET /v0/-/path/to/a/directory/

$ curl -X GET http://127.0.0.1:8080/v0/-/app/
{"entries":[{"name":"git","write":"o","mtime":"2025-08-02T22:51:15.796337Z","ctime":"0001-01-01T00:00:00Z"}],"parent":"/app/"}

Request a list of keys under the indicated directory.

Response will be a JSON blob with the form

{
    "entries" : [
        {
            "name" : "xxx" ,
            "write" : "o" ,
            "mtime" : "2025-08-17T01:43:22.123456Z" ,
            "ctime" : "0001-01-01T00:00:00Z"
        }
    ] ,
    "next" : {
        "dir_id" : dir_id ,
        "pagination" : { "hmac" : "xxx" }
    }
}

ℹ️ In v0.1.2 the JSON structure doesn't include what kind of object each entry is (i.e. file, directory, or symlink). It looks like PR #195 adds a type item with this information. This should be present in v0.1.3.

The next item is for pagination. To read the next page, send the same GET request with page_dir_id and page_hmac query parameters. You can also send a page_entries parameter to limit the number of entries in each "page".

curl -X GET 'http://127.0.0.1:8080/v0/-/app/?page_dir_id=xxx&page_hmac=xxx'

GET /v0/-/path/to/a/key

$ curl -X GET http://127.0.0.1:8080/v0/-/xyzzy
this is a test

Read the value of a key.

The word after /v0/ can be

• - = access the current user's KVs
• t:TEAMNAME = access that team's KVs

PUT /v0/-/path/to/a/key

Store a value. Request body is the value to be stored.

The --mkdir-p flag is assumed, i.e. any intermediate directories which don't exist will be created.

DELETE /v0/-/path/to/a/key

Delete a value.