docs: update api spec according to suggestions from ben

docs/reference/api.md

@@ -14,35 +14,35 @@ For more examples, see "How to use Pebble API". <!-- [David] Link to the how-to
 
 To access the API endpoints over the Unix socket, use the `--unix-socket` option of `curl`. For example:
 
-* TODO
-
-    ```
-    curl ...
-    ```
+```{terminal}
+   :input: curl --unix-socket /path/to/.pebble.socket -XPOST http://localhost/v1/services -d '{"action": "stop", "services": ["svc1"]}'
+{"type":"async","status-code":202,"status":"Accepted","change":"42","result":null}
+```
 
-* TODO
+<br />
 
-    ```
-    curl ...
-    ```
+```{terminal}
+   :input: curl --unix-socket /path/to/.pebble.socket -XGET localhost:4000/v1/changes/42/wait
+{"type":"sync","status-code":200,"status":"OK","result":{"id":"42","kind":"stop","summary":"Stop service \"svc1\"","status":"Done","tasks":[{"id":"42","kind":"stop","summary":"Stop service \"svc1\"","status":"Done","progress":{"label":"","done":1,"total":1},"spawn-time":"2025-01-10T10:59:53.903366896+08:00","ready-time":"2025-01-10T10:59:53.930409771+08:00"}],"ready":true,"spawn-time":"2025-01-10T10:59:53.903373188+08:00","ready-time":"2025-01-10T10:59:53.930410979+08:00"}}
+```
 
 ### Go client
 
 To use the [Go client](https://pkg.go.dev/github.com/canonical/pebble/client) to access API endpoints over the Unix socket, first create a client using `New`, and then call the methods on the returned `Client` struct to interact with the API. For example, to stop a service named `mysvc`:
 
 ```go
-    pebble, err := client.New(&client.Config{Socket: ".pebble.socket"})
-    if err != nil {
-        log.Fatal(err)
-    }
-    changeID, err := pebble.Stop(&client.ServiceOptions{Names: []string{"mysvc"}})
-    if err != nil {
-        log.Fatal(err)
-    }
-    _, err = pebble.WaitChange(changeID, &client.WaitChangeOptions{})
-    if err != nil {
-        log.Fatal(err)
-    }
+pebble, err := client.New(&client.Config{Socket: "/path/to/.pebble.socket"})
+if err != nil {
+    log.Fatal(err)
+}
+changeID, err := pebble.Stop(&client.ServiceOptions{Names: []string{"mysvc"}})
+if err != nil {
+    log.Fatal(err)
+}
+_, err = pebble.WaitChange(changeID, &client.WaitChangeOptions{})
+if err != nil {
+    log.Fatal(err)
+}
 ```
 
 We try to never change the underlying HTTP API in a backwards-incompatible way. However, in rare cases we may change the Go client in a backwards-incompatible way.
@@ -55,8 +55,9 @@ The Ops library for writing and testing Juju charms includes a [Python client fo
 
 ```python
 import ops
-client = ops.pebble.Client('/path/to/.pebble.socket')
-client.start_services(['svc1', 'svc2'])
+client = ops.pebble.Client("/path/to/.pebble.socket")
+changeID = client.stop_services(["mysvc"])
+client.wait_change(changeID)
 ```
 
 For more information, see:
@@ -108,9 +109,8 @@ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
 
 A timestamp is a string in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format with sub-second precision. Here are some examples:
 
-- "2006-01-02T15:04:05Z07:00"
-- "2006-01-02T15:04:05.999999999Z07:00"
-- "2024-12-18T10:45:29.919907089+08:00"
+- "1985-04-12T23:20:50.52Z"
+- "1996-12-19T16:39:57-08:00"
 
 ## Errors
 
@@ -131,7 +131,7 @@ Errors are always returned in JSON format with the following structure:
 
 Possible values for `status-code`:
 
-- 400: Bad request. For example, if a parameter is missing or badly-formatted, such as trying to start a service without providing a the service name.
+- 400: Bad request. For example, if a parameter is missing or badly-formatted, such as trying to start a service without providing a service name.
 - 401: Unauthorized.
 - 404: Not found. For example, if a change with the specified ID does not exist.
 - 500: Internal server error. For example, if the Pebble database is corrupt. If these errors keep happening, please [open an issue](https://github.com/canonical/pebble/issues/new).
@@ -148,8 +148,6 @@ The `result` for some error types includes a `kind` field with the following pos
 
 ## API endpoints
 
-**Work-in-progress. Not all APIs have been included yet.**
-
 <link rel="stylesheet" type="text/css" href="https://unpkg.com/[email protected]/swagger-ui.css" ></link>
 <link rel="stylesheet" type="text/css" href="../../_static/swagger-override.css" ></link>
 <div id="swagger-ui"></div>