docs: add note about public API

docs/abra/hack.md

@@ -20,6 +20,47 @@ Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/bran
 
 Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log.
 
+### Using the `abra` public API
+
+Warning, there is currently no stability promise for the `abra` public API! Most of the internals are exposed in order to allow a free hand for developers to try build stuff. If people start to build things then we can start the discussion on what is useful to have open/closed and keep stable etc. Please let us know if you depend on the APIs!
+
+The `pkg.go.dev` documentation is [here](https://pkg.go.dev/coopcloud.tech/abra). Here's a brief example to get you going:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	abraClient "coopcloud.tech/abra/pkg/client"
+	dockerClient "github.com/docker/docker/client"
+)
+
+func getClient(serverName string) (*dockerClient.Client, error) {
+	cl, err := abraClient.New(serverName)
+	if err != nil {
+		return nil, fmt.Errorf("getClient: %s", err)
+	}
+	return cl, nil
+}
+
+func main() {
+	cl, err := getClient("foo.example.com")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+    // do stuff with the client...
+    // https://pkg.go.dev/github.com/docker/docker/client
+}
+```
+
+Some tools that are making use of the API so far are:
+
+* [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/cmd/kadabra/main.go)
+
 ### Cross-compiling
 
 If there's no official release for the architecture you use, you can cross-compile `abra` very easily. Clone the source code from [here](https://git.coopcloud.tech/coop-cloud/abra) and then: