openapi: 3.1.0
info:
  title: Pebble API
  version: v1
paths:
  /v1/services:
    get:
      summary: List services
      description: Fetch information about specific services (or all of them). Return results ordered by service name.
      tags:
        - services
      parameters:
        - in: query
          name: names
          description: The names of the services to get. To get multiple services, specify this parameter multiple times. If not set, get all services.
          schema:
            type: string
      responses:
        "200":
          description: List of services
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetServices"
              examples:
                list all services:
                  value:
                    - type: sync
                      status-code: 200
                      status: OK
                      result:
                        - name: "svc1"
                          startup: "enabled"
                          current: "active"
                          current-since: "2024-12-11T20:10:33.381993977+08:00"
                        - name: "svc2"
                          startup: "disabled"
                          current: "stopped"
    post:
      summary: Manage services
      description: Services operations, like start/stop/restart a service/services, auto-start default services, and replan.
      tags:
        - services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: The action to perform.
                  enum: ["autostart", "replan", "restart", "start", "stop"]
                services:
                  type: array
                  description: |
                    A list of service names.  Required for "start", "stop", and "restart".
                    Ignored for "replan" and "autostart" (resolved automatically for "autostart" to default services).
                  items:
                    type: string
            examples:
              start one service:
                value:
                  action: start
                  services: ["svc1"]
      responses:
        "202":
          description: Accepted - asynchronous operation started. Returns a change ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostServices"
              examples:
                accepted:
                  value:
                    type: async
                    status-code: 202
                    status: Accepted
                    change: "1"
                    result: null
  /v1/health:
    get:
      summary: Health of specified checks
      description: Fetches healthy status of specified checks.
      tags:
        - checks
      parameters:
        - name: level
          in: query
          description: Health check level.
          schema:
            type: string
            enum: [alive, ready]
        - name: names
          in: query
          description: The names of the checks to get. To get multiple checks, specify this parameter multiple times. If not set, get all checks.
          schema:
            type: string
      responses:
        "200":
          description: Check is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetHealth"
              examples:
                healthy:
                  value:
                    type: sync
                    status-code: 200
                    status: OK
                    result:
                      healthy: true
  /v1/checks:
    get:
      summary: Get checks
      tags:
        - checks
      description: Fetch information about specific health checks (or all of them), ordered by check name.
      parameters:
        - name: level
          in: query
          description: Filter checks by level
          schema:
            type: string
            enum: [alive, ready]
        - name: names
          in: query
          description: The names of the checks to get. To get multiple checks, specify this parameter multiple times. If not set, get all checks.
          schema:
            type: string
      responses:
        "200":
          description: Get checks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetChecks"
              examples:
                get checks:
                  value:
                    type: sync
                    status-code: 200
                    status: OK
                    result:
                      - name: svc1-up
                        status: up
                        threshold: 3
                        change-id: 91
  /v1/changes:
    get:
      summary: Get changes
      tags:
        - changes
      description: Fetch information for the specified changes.
      parameters:
        - name: select
          in: query
          description: Filter changes by status.
          schema:
            type: string
            enum: [all, in-progress, ready]
            default: in-progress
        - name: for
          in: query
          description: Filter changes for a specific service name.
          schema:
            type: string
      responses:
        "200":
          description: Get changes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetChanges"
              example:
                {
                  "type": "sync",
                  "status-code": 200,
                  "status": "OK",
                  "result": [
                      {
                          "id": "4",
                          "kind": "stop",
                          "summary": "Stop service \"svc1\" and 1 more",
                          "status": "Done",
                          "tasks": [
                              {
                                  "id": "7",
                                  "kind": "stop",
                                  "summary": "Stop service \"svc1\"",
                                  "status": "Done",
                                  "progress": {
                                      "label": "",
                                      "done": 1,
                                      "total": 1
                                  },
                                  "spawn-time": "2024-12-24T10:08:14.399194229+08:00",
                                  "ready-time": "2024-12-24T10:08:14.429319813+08:00"
                              },
                              {
                                  "id": "8",
                                  "kind": "stop",
                                  "summary": "Stop service \"svc2\"",
                                  "status": "Done",
                                  "progress": {
                                      "label": "",
                                      "done": 1,
                                      "total": 1
                                  },
                                  "spawn-time": "2024-12-24T10:08:14.399199354+08:00",
                                  "ready-time": "2024-12-24T10:08:14.432387271+08:00"
                              }
                          ],
                          "ready": true,
                          "spawn-time": "2024-12-24T10:08:14.399202521+08:00",
                          "ready-time": "2024-12-24T10:08:14.432389313+08:00"
                      }
                  ]
              }
  /v1/changes/{id}:
    get:
      summary: Get a specific change
      tags:
        - changes
      description: Fetch information about a Change given its ID.
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the change
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChangeObject"
              examples:
                get change:
                  value:
                    type: sync
                    status-code: 200
                    status: OK
                    result:
                      id: 72
                      kind: autostart
                      summary: "Autostart service \"svc1\""
                      status: Done
                      tasks: 
                        - id: 72
                          kind: start
                          summary: "Start service \"svc1\""
                          status: Done,
                          progress:
                            label: ""
                            done: 1
                            total: 1
                          spawn-time: "2024-12-22T20:05:24.855436063+08:00"
                          ready-time: "2024-12-22T20:05:25.866100522+08:00"
                      ready: true,
                      spawn-time: "2024-12-22T20:05:24.855443855+08:00"
                      ready-time: "2024-12-22T20:05:25.866103439+08:00"
    post:
      summary: Perform an action on a change.
      tags:
        - changes
      description: Perform an action on a change. Currently the only supported action is "abort".
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the change
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: The action to perform on the change.
                  enum: [abort]
      responses:
        "200":
          description: abort change
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChangeObject"
              example:
                {
                  "type": "sync",
                  "status-code": 200,
                  "status": "OK",
                  "result": {
                      "id": "8",
                      "kind": "perform-check",
                      "summary": "Perform HTTP check \"check1\"",
                      "status": "Abort",
                      "tasks": [
                          {
                              "id": "14",
                              "kind": "perform-check",
                              "summary": "Perform HTTP check \"check1\"",
                              "status": "Abort",
                              "progress": {
                                  "label": "",
                                  "done": 1,
                                  "total": 1
                              },
                              "spawn-time": "2024-12-24T10:15:31.390053104+08:00"
                          }
                      ],
                      "ready": false,
                      "spawn-time": "2024-12-24T10:15:31.390062521+08:00"
                  }
              }
  /v1/changes/{id}/wait:
    get:
      summary: Wait for a change to complete
      description: |
        Wait for the change to be finished.
        
        If the wait operation succeeds, the result will have the "err" field set to an appropriate error message if the change itself had an error.
      tags:
        - changes
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the change to wait for.
        - in: query
          name: timeout
          schema:
            type: string
          description: |
            Optional timeout (a [duration](#duration)).
            If specified, wait till the change is ready or a timeout occurs, whichever is first.
            If not specified or zero, wait indefinitely until the change is ready.
      responses:
        "200":
          description: Change information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChangeObject"
              examples:
                start service:
                  value:
                    type: sync
                    status-code: 200
                    status: OK
                    result:
                      id: "6"
                      kind: "start"
                      summary: "Start service \"svc1\""
                      status: "Done"
                      tasks:
                        - id: "4"
                          kind: "start"
                          summary: "Start service \"svc1\""
                          status: "Done"
                          progress:
                            label: ""
                            done: 1
                            total: 1
                          spawn-time: "2024-12-12T12:50:29.743512342+08:00"
                          ready-time: "2024-12-12T12:50:30.751092759+08:00"
                      ready: true
                      spawn-time: "2024-12-12T12:50:29.743570175+08:00"
                      ready-time: "2024-12-12T12:50:30.751094634+08:00"
  /v1/system-info:
    get:
      summary: Get system information
      description: |
        Get the version of the Pebble daemon and the boot ID of the system.
      tags:
        - system
      responses:
        "200":
          description: System information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSystemInfo"
              examples:
                system-info:
                  value:
                    - type: sync
                      status-code: 200
                      status: OK
                      result:
                        bootid: "299352d9-4617-4d4b-986a-136a3463b31e"
                        version: "v1.17.0"
components:
  schemas:
    BaseResponse:
      type: object
      properties:
        type:
          type: string
          description: Response type, "sync".
        status-code:
          type: integer
          description: HTTP response status code.
        status:
          type: string
          description: |
            The description of the HTTP status code.

            See the [IANA list](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
    GetChanges:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              type: array
              items:
                $ref: "#/components/schemas/changeInfo"
    ChangeObject:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/changeInfo"
    GetServices:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              type: array
              items:
                $ref: "#/components/schemas/serviceInfo"
    PostServices:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            change:
              type: string
              description: The Change ID of the asynchronous change.
            result:
              type: "null"
    GetSystemInfo:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/systemInfo"
    GetHealth:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              $ref: "#/components/schemas/healthInfo"
    GetChecks:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            result:
              type: array
              items:
                $ref: "#/components/schemas/checkInfo"
    serviceInfo:
      type: object
      properties:
        name:
          type: string
          description: Name of the service.
        startup:
          type: string
          description: Configured startup value.
          enum: ["disabled", "enabled"]
        current:
          type: string
          description: Current status of the service.
          enum: ["active", "backup", "error", "inactive"]
        current-since:
          type: string
          format: date-time
          description: "[Time](#time) the service transitioned to the current status."
    changeInfo:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        summary:
          type: string
        status:
          type: string
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/taskInfo"
        ready:
          type: boolean
        err:
          type: string
        spawn-time:
          type: string
          format: date-time
          description: spawn-time is a [time](#time).
        ready-time:
          type: string
          format: date-time
          description: ready-time is a [time](#time).
        data:
          type: object
          additionalProperties:
            type: string
            format: json-string  # Indicate that values are raw JSON strings.
    taskInfo:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        summary:
          type: string
        status:
          type: string
        log:
          type: array
          items:
            type: string
        progress:
          $ref: "#/components/schemas/taskInfoProgress"
        spawn-time:
          type: string
          format: date-time
          description: spawn-time is a [time](#time).
        ready-time:
          type: string
          format: date-time
          description: ready-time is a [time](#time).
        data:
          type: object
          additionalProperties:
            type: string
            format: json-string # Indicate that values are raw JSON strings。
    taskInfoProgress:
      type: object
      properties:
        label:
          type: string
        done:
          type: integer
        total:
          type: integer
    systemInfo:
      type: object
      properties:
        version:
          type: string
          description: Version of the Pebble daemon
        boot-id:
          type: string
          description: |
            Boot ID of the system, `/proc/sys/kernel/random/boot_id`.
            Or `/proc/sys/kernel/random/uuid` if pebble is PID 1 since in this case we are most likely running in a container
            so we don't care about `/proc/sys/kernel/random/boot_id`.
    healthInfo:
      type: object
      properties:
        healthy:
          type: boolean
          description: True if the check is healthy, false otherwise.
    checkInfo:
      type: object
      properties:
        name:
          type: string
          description: Name of the check
        level:
          type: string
          description: Level of the check
          enum: [alive, ready]
        status:
          type: string
          description: Status of the check
          enum: [down, up]
        failures:
          type: integer
          description: Number of consecutive failures
        threshold:
          type: integer
          description: Failure threshold
        change-id:
          type: string
          description: ID of the change associated with the check