Koha/api/v1/swagger/paths/holds.yaml

---
/holds:
  get:
    x-mojo-to: Holds#list
    operationId: listHolds
    tags:
      - holds
    summary: List holds
    parameters:
      - name: hold_id
        in: query
        description: Internal hold identifier
        type: integer
      - name: patron_id
        in: query
        description: Internal patron identifier
        type: integer
      - name: hold_date
        in: query
        description: Hold
        type: string
        format: date
      - name: biblio_id
        in: query
        description: Internal biblio identifier
        type: integer
      - name: item_group_id
        in: query
        description: Internal item group identifier
        type: integer
      - name: pickup_library_id
        in: query
        description: Internal library identifier for the pickup library
        type: string
      - name: cancellation_date
        in: query
        description: The date the hold was cancelled
        type: string
        format: date
      - name: notes
        in: query
        description: Notes related to this hold
        type: string
      - name: priority
        in: query
        description: Where in the queue the patron sits
        type: integer
      - name: status
        in: query
        description: Found status
        type: string
      - name: timestamp
        in: query
        description: Time of latest update
        type: string
      - name: item_id
        in: query
        description: Internal item identifier
        type: integer
      - name: waiting_date
        in: query
        description: Date the item was marked as waiting for the patron
        type: string
      - name: expiration_date
        in: query
        description: Date the hold expires
        type: string
      - name: lowest_priority
        in: query
        description: Lowest priority
        type: boolean
      - name: suspended
        in: query
        description: Suspended
        type: boolean
      - name: suspended_until
        in: query
        description: Suspended until
        type: string
      - name: non_priority
        in: query
        description: Non priority hold
        type: boolean
      - $ref: "../swagger.yaml#/parameters/match"
      - $ref: "../swagger.yaml#/parameters/order_by"
      - $ref: "../swagger.yaml#/parameters/page"
      - $ref: "../swagger.yaml#/parameters/per_page"
      - $ref: "../swagger.yaml#/parameters/q_param"
      - $ref: "../swagger.yaml#/parameters/q_body"
      - $ref: "../swagger.yaml#/parameters/q_header"
      - $ref: "../swagger.yaml#/parameters/request_id_header"
    produces:
      - application/json
    responses:
      "200":
        description: A list of holds
        schema:
          $ref: "../swagger.yaml#/definitions/holds"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Borrower not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds
  post:
    x-mojo-to: Holds#add
    operationId: addHold
    tags:
      - holds
    summary: Place hold
    parameters:
      - name: body
        in: body
        description: A JSON object containing informations about the new hold
        required: true
        schema:
          type: object
          properties:
            patron_id:
              description: Internal patron identifier
              type: integer
            biblio_id:
              description: Internal biblio identifier
              type:
                - integer
                - "null"
            item_group_id:
              description: Internal item group identifier
              type:
                - integer
                - "null"
            hold_date:
              description: The date the hold was placed
              type:
                - string
                - "null"
              format: date
            item_id:
              description: Internal item identifier
              type:
                - integer
                - "null"
            pickup_library_id:
              description: Internal library identifier for the pickup library
              type: string
            expiration_date:
              description: Hold end date
              type:
                - string
                - "null"
              format: date
            notes:
              description: Notes related to this hold
              type:
                - string
                - "null"
            item_type:
              description: Limit hold on one itemtype (ignored for item-level holds)
              type:
                - string
                - "null"
            non_priority:
              description: Set this hold as non priority
              type:
                - boolean
                - "null"
          required:
            - patron_id
            - pickup_library_id
          additionalProperties: false
      - name: x-koha-override
        in: header
        required: false
        description: Overrides list sent as a request header
        type: array
        items:
          type: string
          enum:
            - any
        collectionFormat: csv
    consumes:
      - application/json
    produces:
      - application/json
    responses:
      "201":
        description: Created hold
        schema:
          $ref: "../swagger.yaml#/definitions/hold"
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Borrower not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: "1"
"/holds/{hold_id}":
  patch:
    x-mojo-to: Holds#edit
    operationId: editHold
    tags:
      - holds
    summary: Update hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - name: body
        in: body
        description: A JSON object containing fields to modify
        required: true
        schema:
          type: object
          properties:
            priority:
              description: Position in waiting queue
              type: integer
              minimum: 1
            pickup_library_id:
              description: Internal library identifier for the pickup library
              type: string
            suspended_until:
              description: Date until which the hold has been suspended
              type: string
              format: date-time
          additionalProperties: false
    consumes:
      - application/json
    produces:
      - application/json
    responses:
      "200":
        description: Updated hold
        schema:
          $ref: "../swagger.yaml#/definitions/hold"
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: "1"
  put:
    x-mojo-to: Holds#edit
    operationId: overwriteHold
    tags:
      - holds
    summary: Update hold
    description: This route is being deprecated and will be removed in future releases.
      Please migrate your project to use PATCH /holds/{hold_id} instead.
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - name: body
        in: body
        description: A JSON object containing fields to modify
        required: true
        schema:
          type: object
          properties:
            priority:
              description: Position in waiting queue
              type: integer
              minimum: 1
            pickup_library_id:
              description: Internal library identifier for the pickup library
              type: string
            suspended_until:
              description: Date until which the hold has been suspended
              type: string
              format: date-time
          additionalProperties: false
    consumes:
      - application/json
    produces:
      - application/json
    responses:
      "200":
        description: Updated hold
        schema:
          $ref: "../swagger.yaml#/definitions/hold"
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: "1"
  delete:
    x-mojo-to: Holds#delete
    operationId: deleteHold
    tags:
      - holds
    summary: Cancel hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
    produces:
      - application/json
    responses:
      "204":
        description: Hold deleted
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds
"/holds/{hold_id}/priority":
  put:
    x-mojo-to: Holds#update_priority
    operationId: updateHoldPriority
    tags:
      - holds
    summary: Update priority for the hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - name: body
        in: body
        description: An integer representing the new priority to be set for the hold
        required: true
        schema:
          type: integer
    produces:
      - application/json
    responses:
      "200":
        description: The new priority value for the hold
        schema:
          type: integer
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Access forbidden
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Biblio not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "409":
        description: Unable to perform action on biblio
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: modify_holds_priority
"/holds/{hold_id}/suspension":
  post:
    x-mojo-to: Holds#suspend
    operationId: suspendHold
    tags:
      - holds
    summary: Suspend the hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - name: body
        in: body
        description: A JSON object containing fields to modify
        required: false
        schema:
          type: object
          properties:
            end_date:
              description: Date the hold suspension expires
              type: string
              format: date
          additionalProperties: false
    consumes:
      - application/json
    produces:
      - application/json
    responses:
      "201":
        description: Hold suspended
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds
  delete:
    x-mojo-to: Holds#resume
    operationId: resumeHold
    tags:
      - holds
    summary: Resume hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
    consumes:
      - application/json
    produces:
      - application/json
    responses:
      "204":
        description: Hold resumed
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds
"/holds/{hold_id}/pickup_locations":
  get:
    x-mojo-to: Holds#pickup_locations
    operationId: getHoldPickupLocations
    tags:
      - holds
    summary: Get valid pickup locations for hold
    parameters:
      - name: x-koha-override
        in: header
        required: false
        description: Overrides list sent as a request header
        type: array
        items:
          type: string
          enum:
            - any
        collectionFormat: csv
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - $ref: "../swagger.yaml#/parameters/match"
      - $ref: "../swagger.yaml#/parameters/order_by"
      - $ref: "../swagger.yaml#/parameters/page"
      - $ref: "../swagger.yaml#/parameters/per_page"
      - $ref: "../swagger.yaml#/parameters/q_param"
      - $ref: "../swagger.yaml#/parameters/q_body"
      - $ref: "../swagger.yaml#/parameters/q_header"
      - $ref: "../swagger.yaml#/parameters/request_id_header"
    produces:
      - application/json
    responses:
      "200":
        description: Hold pickup location
        schema:
          type: array
          items:
            $ref: "../swagger.yaml#/definitions/library"
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Hold pickup location list not allowed
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: |
          Internal server error. Possible `error_code` attribute values:

          * `internal_server_error`          
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds
"/holds/{hold_id}/pickup_location":
  put:
    x-mojo-to: Holds#update_pickup_location
    operationId: updateHoldPickupLocation
    tags:
      - holds
    summary: Update pickup location for the hold
    description: Set a new pickup location for the hold
    parameters:
      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
      - name: body
        in: body
        description: Pickup location
        required: true
        schema:
          type: object
          properties:
            pickup_library_id:
              type: string
              description: Internal identifier for the pickup library
          additionalProperties: false
    produces:
      - application/json
    responses:
      "200":
        description: The new pickup location value for the hold
        schema:
          type: object
          properties:
            pickup_library_id:
              type: string
              description: Internal identifier for the pickup library
          additionalProperties: false
      "400":
        description: Missing or wrong parameters
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "401":
        description: Authentication required
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "403":
        description: Access forbidden
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "404":
        description: Hold not found
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "409":
        description: Unable to perform action on hold
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "500":
        description: Internal error
        schema:
          $ref: "../swagger.yaml#/definitions/error"
      "503":
        description: Under maintenance
        schema:
          $ref: "../swagger.yaml#/definitions/error"
    x-koha-authorization:
      permissions:
        reserveforothers: place_holds