spec.yaml

openapi: "3.0.2"
info:
  title: PiHole Management API
  description: A management webservice to be run locally on a PiHole instance
  version: "1.0"
servers:
  - url: http://pi.hole:8080/
paths:
  /status:
    get:
      description: Status of the PiHole service and webservice
      responses:
        "200":
          description: All systems normal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "201":
          description: PiHole running but not enabled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "500":
          description: PiHole service is unhealthy or not running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
  /status/{action}:
    post:
      parameters:
        - name: action
          in: path
          required: true
          schema:
            type: string
            example: restart
      responses:
        "200":
          description: All systems normal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "201":
          description: PiHole running but not enabled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
        "400":
          description: Illegal Request
          content:
            text/text:
              schema:
                type: string
                example: "Invalid request"
  /gravity:
    get:
      description: Returns a list of all gravity sources
      responses:
        "200":
          description: List of configured Gravity sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GravityObj"
    post:
      description: Adds a new gravity source
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GravityObj"
      responses:
        "200":
          $ref: "#/components/responses/unchanged"
        "201":
          $ref: "#/components/responses/updated"
    patch:
      description: Update gravity (equivalent to `pihole -g`)
      responses:
        "200":
          $ref: "#/components/responses/unchanged"

  /gravity/{id}:
    delete:
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: integer
            example: 1
      responses:
        "200":
          $ref: "#/components/responses/deleted"
  /records:
    get:
      description: Returns a list of custom DNS records
      responses:
        "200":
          $ref: "#/components/responses/records"
    post:
      description: Add a custom DNS record
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Record"
      responses:
        "200":
          description: Unchanged
          $ref: "#/components/responses/records"
        "201":
          description: Record added or updated
          $ref: "#/components/responses/records"
        "418":
          description: Invalid record type
          $ref: "#/components/responses/invalidRecordType"
    delete:
      description: Remove a custom record
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRecord"
      responses:
        "200":
          $ref: "#/components/responses/records"
        "201":
          $ref: "#/components/responses/deleted"
        "418":
          description: Invalid record type
          $ref: "#/components/responses/invalidRecordType"
  /overrides/{list}:
    description: Return the Allow or Deny lists

    get:
      parameters:
        - name: list
          required: true
          in: path
          schema:
            type: string
            example: allow
      responses:
        "200":
          $ref: "#/components/responses/override"

components:
  responses:
    override:
      description: Allow/Block list
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Overrides"
    invalidRecordType:
      description: Invalid DNS record type specified
      content:
        application/json:
          schema:
            type: string
            example: "'TEAPOT' is not a valid record type"
    records:
      description: List of DNS records
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Record"
    unchanged:
      description: Object unchanged
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GravityObj"
    updated:
      description: Object updated
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GravityObj"
    deleted:
      description: The object was deleted
      content:
        application/json:
          schema:
            type: string
            example: "Object deleted successfully"

  schemas:
    Overrides:
      description: List of overrides
      type: array
      items:
        type: string
        example: google.com
    DeleteRecord:
      type: object
      required:
        - type
        - domain
      properties:
        type:
          type: string
          example: CNAME
          description: CNAME or A
        domain:
          type: string
          example: endres.io
          description: The domain to resolve
    Record:
      type: object
      required:
        - type
        - domain
        - destination
      properties:
        type:
          type: string
          example: CNAME
          description: CNAME or A
        domain:
          type: string
          example: google.com
          description: The domain to resolve
        destination:
          type: string
          example: 8.8.8.8
          description: The destination IP or DNS record
    Status:
      type: object
      required:
        - listening
        - ipv4
        - ipv6
        - blocking
      properties:
        listening:
          type: boolean
          example: true
        ipv4:
          $ref: "#/components/schemas/UdpTcp"
        ipv6:
          $ref: "#/components/schemas/UdpTcp"

        blocking:
          type: boolean
          example: true
    UdpTcp:
      type: object
      required:
        - udp
        - tcp
      properties:
        udp:
          type: boolean
          example: true
        tcp:
          type: boolean
          example: true

    GravityObj:
      type: object
      required:
        - address
      properties:
        id:
          type: integer
          example: 1
        address:
          type: string
          example: https://pi.hole/adlist.txt
        comment:
          type: string
          example: My adlist for PiHole