openapi: 3.2.0
info:
  title: Arthur Online Utilities API
  version: 2.0.0
  contact:
    name: Arthur Online API Support
    url: https://support.arthuronline.co.uk/
  termsOfService: https://www.arthuronline.co.uk/terms-and-conditions/
  x-derived-by: API Evangelist enrichment pipeline
  x-derived-date: '2026-07-26'
  x-derived-from: collections/arthur-online.postman_collection.json
  description: 'Operations tagged Utilities across 3 of this provider''s published API definitions: arthur-online-properties-openapi.yml, arthur-online-units-openapi.yml, arthur-online-utilities-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.arthuronline.co.uk/v2
  description: Arthur API v2 production
security:
- arthurOAuth: []
tags:
- name: Utilities
paths:
  /properties/{property_id}/utilities:
    get:
      operationId: listUtilitiesOnProperty
      summary: List Utilities On Property
      tags:
      - Utilities
      parameters:
      - name: property_id
        in: path
        required: true
        description: Arthur property id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: This endpoint retrieves a list of utilities associated with the given property ID.
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createUtilityOnProperty
      summary: Create Utility On Property
      tags:
      - Utilities
      parameters:
      - name: property_id
        in: path
        required: true
        description: Arthur property id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "Use this endpoint to create a new utility record for the  property . The API will return the saved data and a unique utility ID.\n\nSupported Fields \n The following fields are supported for the request body\n\nField \n Example \n Type \n Required? \n\ntype \n gas \n String \n Yes \n\nnotes \n behind back doors \n String \n No \n\nserial_number \n GA212FP21 \n String \n No \n\naccount_number \n 12344321 \n string \n No \n\nprovider \n company_name \n string \n No"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: gas
                notes:
                  type: string
                  example: behind back doors
                serial_number:
                  type: string
                  example: GA212FP21
                account_number:
                  type: string
                  example: '12344321'
                provider:
                  type: string
                  example: company_name
              required:
              - type
            example:
              type: gas
              serial_number: Created serial number
              account_number: '12344321'
              provider: ''
              last_reading_value: null
              last_reading_date: null
              notes: ''
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.arthuronline.co.uk/v2
      description: Arthur API v2 production
  /units/{unit_id}/utilities:
    get:
      operationId: listUtilitiesOnUnit
      summary: List Utilities On Unit
      tags:
      - Utilities
      parameters:
      - name: unit_id
        in: path
        required: true
        description: Arthur unit id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: This endpoint retrieves a list of utilities associated with the given unit ID.
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createUtilityOnUnit
      summary: Create Utility On Unit
      tags:
      - Utilities
      parameters:
      - name: unit_id
        in: path
        required: true
        description: Arthur unit id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "Use this endpoint to create a new utility record for the unit . The API will return the saved data and a unique utility ID.\n\nSupported Fields \n The following fields are supported for the request body\n\nField \n Example \n Type \n Required? \n\ntype \n gas \n String \n Yes \n\nnotes \n behind back doors \n String \n No \n\nserial_number \n GA212FP21 \n String \n No \n\naccount_number \n 12344321 \n string \n No \n\nprovider \n company_name \n string \n No"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: gas
                notes:
                  type: string
                  example: behind back doors
                serial_number:
                  type: string
                  example: GA212FP21
                account_number:
                  type: string
                  example: '12344321'
                provider:
                  type: string
                  example: company_name
              required:
              - type
            example:
              type: gas
              serial_number: Created serial number
              account_number: '12344321'
              provider: ''
              last_reading_value: null
              last_reading_date: null
              notes: ''
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.arthuronline.co.uk/v2
      description: Arthur API v2 production
  /utilities:
    get:
      operationId: listUtilities
      summary: List Utilities
      tags:
      - Utilities
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Filter by type (e.g. gas, water, eletric)
      - name: serial_number
        in: query
        required: false
        schema:
          type: string
        description: Filter by serial number
      - name: account_number
        in: query
        required: false
        schema:
          type: string
        description: Filter by account number
      - name: provider
        in: query
        required: false
        schema:
          type: string
        description: Filter by provider
      - name: created
        in: query
        required: false
        schema:
          type: string
        description: Filter by the created date. Use the format yyyy-mm-dd to input the date.
      - name: modified
        in: query
        required: false
        schema:
          type: string
        description: Filter by the modified date. Use the format yyyy-mm-dd to input the date.
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: 'This retrieves a list of utilities.


        See available filters below to customize the list of utilities returned.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.arthuronline.co.uk/v2
      description: Arthur API v2 production
  /utilities/{utility_id}:
    get:
      operationId: viewUtility
      summary: View Utility
      tags:
      - Utilities
      parameters:
      - name: utility_id
        in: path
        required: true
        description: Arthur utility id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: 'This API endpoint retrieves the details of a single utility, identified by its unique  utility_id .


        Use this endpoint to view the specific details of a utility record.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUtility
      summary: Update Utility
      tags:
      - Utilities
      parameters:
      - name: utility_id
        in: path
        required: true
        description: Arthur utility id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "This endpoint updates an existing utility. The API will return the updated data for the utility in the response.\n\nSupported Fields \n The following fields are supported for the request body\n\nField \n Example \n Type \n Required? \n\ntype \n gas \n String \n No \n\nnotes \n behind back doors \n String \n No \n\nserial_number \n GA212FP21 \n String \n No \n\naccount_number \n 12344321 \n string \n No \n\nprovider \n company_name \n string \n No"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: gas
                notes:
                  type: string
                  example: behind back doors
                serial_number:
                  type: string
                  example: GA212FP21
                account_number:
                  type: string
                  example: '12344321'
                provider:
                  type: string
                  example: company_name
            example:
              serial_number: Updated serial number
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUtility
      summary: Delete Utility
      tags:
      - Utilities
      parameters:
      - name: utility_id
        in: path
        required: true
        description: Arthur utility id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: This endpoint deletes an existing utility using the utility  id .
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.arthuronline.co.uk/v2
      description: Arthur API v2 production
components:
  parameters:
    Direction:
      name: direction
      in: query
      required: false
      description: Sort direction.
      schema:
        type: string
        enum:
        - ASC
        - DESC
    Sort:
      name: sort
      in: query
      required: false
      description: Field to sort the collection by.
      schema:
        type: string
    Strict:
      name: strict
      in: query
      required: false
      description: When true, abort the request instead of auto-creating an unknown Simple type. POST and PUT only.
      schema:
        type: boolean
    EntityId:
      name: X-EntityID
      in: header
      required: true
      description: The Arthur entity (account) the request is scoped to. Mandatory on every API call.
      schema:
        type: string
    Page:
      name: page
      in: query
      required: false
      description: Page number, between 1 and the total number of pages.
      schema:
        type: integer
        minimum: 1
    Limit:
      name: limit
      in: query
      required: false
      description: Items per page, between 1 and 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The request was sent to a location that does not exist in the API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or expired access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: expired_token
            message: This token has expired.
  schemas:
    Error:
      type: object
      description: Arthur error envelope.
      properties:
        status:
          type: integer
        error:
          type: string
          description: Machine-readable error code, e.g. expired_token.
        message:
          type: string
  securitySchemes:
    arthurOAuth:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow. Access tokens are valid for 14 days; refresh tokens for 21 days. Register an application in Arthur Settings > OAuth Applications to obtain a client_id and client_secret.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.arthuronline.co.uk/oauth/authorize
          tokenUrl: https://auth.arthuronline.co.uk/oauth/token
          refreshUrl: https://auth.arthuronline.co.uk/oauth/token
          scopes: {}
x-refined-from:
- arthur-online-properties-openapi.yml
- arthur-online-units-openapi.yml
- arthur-online-utilities-openapi.yml