API¶

Pebble exposes an HTTP API that remote clients can use to interact with the daemon. The API has endpoints for starting and stopping services, adding configuration layers to the plan, and so on.

The API uses HTTP over a Unix socket, with access to the API controlled by user ID. If pebble run is started with the --http <address> option, Pebble exposes a limited set of open-access endpoints (see API access levels) using the given TCP address.

Using the API¶

You can use different tools and clients to access the API.

For more examples, see “How to use Pebble API”.

curl¶

To access the API endpoints over the Unix socket, use the --unix-socket option of curl. For example:

TODO
```
curl ...
```
TODO
```
curl ...
```

Go client¶

To use the Go 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:

    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)
    }

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.

For more information, see the Go client documentation.

Python client¶

The Ops library for writing and testing Juju charms includes a Python client for Pebble API. You can use the Python client to access the API endpoints over the Unix socket. For example:

import ops
client = ops.pebble.Client('/path/to/.pebble.socket')
client.start_services(['svc1', 'svc2'])

For more information, see:

Structure of the API¶

Pebble requests use the GET method for reads and the POST method for writes.

Some GET requests take optional query parameters for configuring or filtering the response, for example, /v1/services?names=svc1 to only fetch the data for svc1.

All data sent to the API in POST bodies and all response data from the API is in JSON format. Requests should have a Content-Type: application/json header.

There are two main types of requests: synchronous (“sync”), and asynchronous (“async”) for operations that can take some time to execute. Synchronous responses have the following structure:

{
  "type": "sync",
  "status-code": 200,
  "status": "OK",
  "result": "<object-or-array>"
}

Asynchronous responses include a “change” field instead of “result”, which is the ID of the change operation that can be used to query the operation’s status or wait for it to finish:

{
  "type": "async",
  "status-code": 202,
  "status": "Accepted",
  "change": "<change-id>"
}

Data formats¶

Some API parameters and response fields use specific formats as defined below.

Duration¶

The format of a duration string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”.

Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

Time¶

A timestamp is a string in the RFC 3339 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”

Errors¶

API endpoints may return errors as 4xx status codes (client errors) and 5xx status codes (server errors).

Errors are always returned in JSON format with the following structure:

{
  "type": "error",
  "status-code": 400,
  "status": "Bad Request",
  "result": {
    "message": "select should be one of: all,in-progress,ready"
  }
}

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.
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.

The result for some error types includes a kind field with the following possible values:

daemon-restart
generic-file-error
login-required
no-default-services
not-found
permission-denied
system-restart

API endpoints¶

Work-in-progress. Not all APIs have been included yet.