open-api.yaml

openapi: 3.0.0
info:
  title: Broker API
  version: 1.0.0
  description: API for retrieving broker data

components:
  parameters:
    Tenant:
      name: X-Okapi-Tenant
      in: header
      description: Okapi Tenant
      required: false
      schema:
        type: string
        pattern: '^[_a-z][_a-z0-9]*$'
    RequesterRequestId:
      name: requester_req_id
      in: query
      description: Filter Ill transactions by requester request id
      schema:
        type: string
    IllTransactionId:
      name: ill_transaction_id
      in: query
      schema:
        type: string
      description: Filter by ILL transaction ID
    RequesterSymbol:
      name: requester_symbol
      in: query
      description: Filter by requester symbol
      schema:
        type: string
    Offset:
      name: offset
      in: query
      description: Offset for pagination (first item is 0)
      schema:
        type: integer
        format: int32
    Limit:
      name: limit
      in: query
      description: Limit for pagination
      schema:
        type: integer
        format: int32
    ArchiveDelay:
      name: archive_delay
      in: query
      description: How old ILL Transaction to archive, for example "48h"
      required: true
      schema:
        type: string
    ArchiveStatus:
      name: archive_status
      in: query
      description: Comma separated list of statuses to archive, for example "LoanCompleted,CopyCompleted,Unfilled"
      required: true
      schema:
        type: string
    Cql:
      name: cql
      in: query
      description: CQL query for filtering results
      schema:
        type: string
    Side:
      name: side
      in: query
      description: Patron request side, valid values "borrowing" and "lending"
      schema:
        type: string
    Symbol:
      name: symbol
      in: query
      description: Symbol for access control
      schema:
        type: string
    NotificationKind:
      name: kind
      in: query
      description: Notification kind, valid values "note" and "condition"
      schema:
        type: string
        enum:
          - note
          - condition
    PatronRequestId:
      name: pr_id
      in: query
      description: Patron request ID
      schema:
        type: string
    Facets:
      name: facets
      in: query
      description: Comma separated list of facet names to include in the response.
        Supported values are "requester_name", "requester_symbol", "supplier_name",
        "supplier_symbol"; unsupported facet names result in a 400 response.
        For example "requester_symbol,supplier_symbol"
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - requester_symbol
            - supplier_symbol
            - requester_name
            - supplier_name
  schemas:
    Index:
      type: object
      properties:
        revision:
          type: string
          description: VCS revision
        signature:
          type: string
          description: Application signature
        links:
          type: object
          properties:
            illTransactionsLink:
              type: string
              description: Link to ILL transactions
            peersLink:
              type: string
              description: Link to peers
            eventsLink:
              type: string
              description: Link to events
            locatedSuppliersLink:
              type: string
              description: Link to located suppliers
            patronRequestsLink:
              type: string
              description: Link to patron request
          required:
            - eventsLink
            - illTransactionsLink
            - peersLink
            - locatedSuppliersLink
            - patronRequestsLink
      required:
        - revision
        - signature
        - links
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
    StatusMessage:
      type: object
      properties:
        status:
          type: string
          description: Process status
      required:
        - status
    IllTransactions:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of ILL transactions
          items:
            $ref: '#/components/schemas/IllTransaction'
    Events:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of events
          items:
            $ref: '#/components/schemas/Event'
    Peers:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of peers
          items:
            $ref: '#/components/schemas/Peer'
    LocatedSuppliers:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of peers
          items:
            $ref: '#/components/schemas/LocatedSupplier'
    FacetsResult:
      type: array
      description: List of facets for the result
      items:
        type: object
        required:
          - name
          - values
        properties:
          name:
            type: string
            description: Facet name
          values:
            type: array
            description: List of facet values. At most 100 entries are returned.
            items:
              $ref: '#/components/schemas/FacetResultValue'
    FacetResultValue:
      type: object
      required:
        - value
        - count
      properties:
        value:
          type: string
          description: Facet value
        count:
          type: integer
          format: int64
          description: Count of items for this facet value
    About:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          format: int64
          description: Total number of items in the result
        nextLink:
          type: string
          description: Link to the next page of results
        prevLink:
          type: string
          description: Link to the previous page of results
        firstLink:
          type: string
          description: Link to the first page of results
        lastLink:
          type: string
          description: Link to the last page of results
    AboutWithFacets:
      allOf:
        - $ref: '#/components/schemas/About'
        - type: object
          properties:
            facets:
              $ref: '#/components/schemas/FacetsResult'
    Event:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the event
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the event
        illTransactionID:
          type: string
          description: ID of the ILL transaction (if applicable)
        patronRequestID:
          type: string
          description: ID of the Patron request (if applicable)
        eventType:
          type: string
          description: Type of the event
        eventName:
          type: string
          description: Name of the event
        eventStatus:
          type: string
          description: Status of the event
        eventData:
          type: object
          description: Data associated with the event
          additionalProperties: true
        resultData:
          type: object
          description: Result data of the event
          additionalProperties: true
        parentID:
          type: string
          description: Parent event ID
      required:  # List required fields if any
        - id
        - illTransactionID
        - timestamp
        - eventType
        - eventName
        - eventStatus
    IllTransaction:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the ILL transaction
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the transaction
        requesterSymbol:
          type: string
          description: Symbol of the requesting institution
        requesterID:
          type: string
          description: ID of the requesting institution
        lastRequesterAction:
          type: string
          description: Last action performed by the requester
        prevRequesterAction:
          type: string
          description: Previous action performed by the requester
        supplierSymbol:
          type: string
          description: Symbol of the supplying institution
        requesterRequestID:
          type: string
          description: ID of the request from the requester's side
        supplierRequestID:
          type: string
          description: ID of the request from the supplier's side
        lastSupplierStatus:
          type: string
          description: Last status update from the supplier
        prevSupplierStatus:
          type: string
          description: Previous status update from the supplier
        illTransactionData:
          type: object
          description: Result data of the event
          additionalProperties: true
        eventsLink:
          type: string
          description: Link to Ill Transaction events
        locatedSuppliersLink:
          type: string
          description: Link to located Suppliers
        requesterPeerLink:
          type: string
          description: Link to requester Peer
      required:
        - id
        - timestamp
        - requesterSymbol
        - requesterID
        - lastRequesterAction
        - prevRequesterAction
        - supplierSymbol
        - requesterRequestID
        - supplierRequestID
        - lastSupplierStatus
        - prevSupplierStatus
        - illTransactionData
        - eventsLink
        - locatedSuppliersLink
        - requesterPeerLink
    Peer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the peer
        symbols:
          type: array
          items:
            type: string
          description: Unique symbol representing the peer
        branchSymbols:
          type: array
          items:
            type: string
          description: Symbols of peer branches
        name:
          type: string
          description: Name of the peer
        url:
          type: string
          description: Network URL of the peer
        refreshPolicy:
          type: string
          enum: [never, transaction]
          description: Policy for refreshing peer information (never, transaction)
        refreshTime:
          type: string
          format: date-time
          description: Timestamp of refresh
        loansCount:
          type: integer
          format: int32
          description: Count of loans
        borrowsCount:
          type: integer
          format: int32
          description: Count of borrows
        vendor:
          type: string
          description: Vendor of the ISO18626 implementation, e.g "Alma", "ReShare"
        brokerMode:
          type: string
          enum: [opaque, transparent, translucent]
          description: Broker mode, e.g "opaque", "transparent" or "translucent"
        customData:
          type: object
          description: Custom data of peer
          additionalProperties: true
        httpHeaders:
          type: object
          description: HTTP headers to be sent with requests to the peer
          additionalProperties:
            type: string
      required:
        - id
        - symbols
        - name
        - url
        - refreshPolicy
        - vendor
        - brokerMode

    LocatedSupplier:
      type: object
      properties:
        id:
          type: string
          description: Generate ID
        illTransactionID:
          type: string
          description: Ill Transaction ID
        supplierID:
          type: string
          description: Supplier ID from peer table
        supplierSymbol:
          type: string
          description: Supplier symbol to use for communication
        ordinal:
          type: integer
          format: int32
          description: Ordinal number for ordering
        supplierStatus:
          type: string
          description: Supplier status, possible values (new, selected, skipped)
        prevAction:
          type: string
          description: Previous requester action
        prevStatus:
          type: string
          description: Previous supplier transaction status
        lastAction:
          type: string
          description: Latest requester action
        lastStatus:
          type: string
          description: Latest supplier transaction status
        localID:
          type: string
          description: Item local ID
        prevReason:
          type: string
          description: Previous requester reason
        lastReason:
          type: string
          description: Latest requester reason
        supplierRequestID:
          type: string
          description: Supplier request ID
        supplierPeerLink:
          type: string
          description: Link to supplier Peer
      required:
        - id
        - illTransactionID
        - supplierID
        - supplierSymbol
        - ordinal
        - supplierPeerLink
    PatronRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the patron request
        createdAt:
          type: string
          format: date-time
          description: Timestamp of the patron request creation
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the patron request last update
        illRequest:
          type: object
          description: JSON of ISO18626 request
        state:
          type: string
          description: Patron request state
        side:
          type: string
          description: Patron request side - borrowing or lending
        patron:
          type: string
          description: User who requested item
        requesterSymbol:
          type: string
          description: Requester symbol
        supplierSymbol:
          type: string
          description: Supplier symbol
        requesterRequestId:
          type: string
          description: Requester patron request ID
        needsAttention:
          type: boolean
          description: Indicates if the request needs attention
        hasCost:
          type: boolean
          description: Indicates if the request has a cost notification
        unreadNotificationsCount:
          type: integer
          format: int64
          description: Number of unread notifications for this request
        lastAction:
          type: string
          description: Latest action on this request
        lastActionOutcome:
          type: string
          description: Latest action outcome
        lastActionResult:
          type: string
          description: Latest action status ("NEW", "PROCESSING", "SUCCESS", "PROBLEM", "ERROR")
        items:
          type: array
          description: List of patron request items
          items:
            $ref: '#/components/schemas/PrItem'
        notificationsLink:
          type: string
          description: Link to notifications for this patron request
        itemsLink:
          type: string
          description: Link to items for this patron request
        availableActionsLink:
          type: string
          description: Link to available actions for this patron request
        illTransactionLink:
          type: string
          description: Link to related ILL transaction lookup
        eventsLink:
          type: string
          description: Link to events for this patron request
        terminalState:
          type: boolean
          description: Indicates if the request is in terminal state
        illResponse:
          type: object
          description: JSON of ISO18626 supplying agency message
        internalNote:
          type: string
          description: Staff-only internal note, local to this request and never shared with peers
        requesterName:
          type: string
          description: Name of the requester peer
        supplierName:
          type: string
          description: Name of the supplier peer
        nextReqId:
          type: string
          description: ID of the next patron request in the sequence
        prevReqId:
          type: string
          description: ID of the previous patron request in the sequence
        retryBibInfo:
          $ref: '#/components/schemas/BibliographicInfo'
      required:
        - id
        - createdAt
        - state
        - side
        - illRequest
        - needsAttention
        - hasCost
        - unreadNotificationsCount
        - terminalState
    PatronRequests:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/AboutWithFacets'
        items:
          type: array
          description: List of patron request
          items:
            $ref: '#/components/schemas/PatronRequest'

    CreatePatronRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the patron request
        illRequest:
          type: object
          description: JSON of ISO18626 request
        patron:
          type: string
          description: User who requested item
        requesterSymbol:
          type: string
          description: Requester symbol
        internalNote:
          type: string
          description: Staff-only internal note, local to this request and never shared with peers
      required:
        - illRequest

    UpdateInternalNote:
      type: object
      properties:
        internalNote:
          type: string
          description: Staff-only internal note text. Send an empty string or omit to clear the note.

    ExecuteAction:
      type: object
      properties:
        action:
          type: string
          description: Action to execute
        actionParams:
          type: object
          description: Action parameters
      required:
        - action

    AllowedAction:
      type: object
      properties:
        name:
          type: string
          description: Name of the action
        parameters:
          type: array
          description: List of parameters for this action
          items:
            type: string
        primary:
          type: boolean
          description: Indicates if this action is primary action for the state
        available:
          type: boolean
          description: Indicates if this action is available for execution in the current state
      required:
        - name
        - parameters
        - available

    AllowedActions:
      type: object
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AllowedAction'
      required:
        - actions

    ActionResult:
      type: object
      properties:
        result:
          type: string
          description: Action result
        message:
          type: string
          description: Action message
        outcome:
          type: string
          description: Action outcome ("success", "failure", "review")
        fromState:
          type: string
          description: State before action execution
        toState:
          type: string
          description: State after action execution
      required:
        - result
        - outcome
        - fromState

    SseResult:
      type: object
      properties:
        event:
          type: string
          description: Event name, for example 'message-supplier'
        data:
          type: object
          description: Data of the event, for example ISO18626 message
      required:
        - event
        - data

    StateModel:
      title: StateModel
      type: object
      description: ReShare state model definition
      additionalProperties: false
      properties:
        type:
          type: string
          description: Self-referential type
          enum:
            - StateModel
        name:
          type: string
          description: Name of the state model
        desc:
          type: string
          description: Description of the state model
        version:
          type: string
          description: Version of the state model in SemVer
        states:
          type: array
          description: A list of all allowed states
          items:
            $ref: '#/components/schemas/ModelState'
      required:
        - name
        - states
        - type
        - version

    StateModelCapabilities:
      title: StateModelCapabilities
      type: object
      description: Built-in states, actions and message events supported by the broker
      additionalProperties: false
      properties:
        requesterStates:
          type: array
          items:
            type: string
        supplierStates:
          type: array
          items:
            type: string
        requesterActions:
          type: array
          items:
            $ref: '#/components/schemas/ActionCapability'
        supplierActions:
          type: array
          items:
            $ref: '#/components/schemas/ActionCapability'
        requesterMessageEvents:
          type: array
          items:
            type: string
        supplierMessageEvents:
          type: array
          items:
            type: string
      required:
        - requesterStates
        - supplierStates
        - requesterActions
        - supplierActions
        - requesterMessageEvents
        - supplierMessageEvents
    ActionCapability:
      title: ActionCapability
      type: object
      description: Definition of an action and its parameters supported by the broker.
        Action parameters are defined separately from actions because the same parameters
        can be used for multiple actions, for example note parameter is supported for
        multiple actions but is not required for all of them.
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the action parameter
        parameters:
          type: array
          description: List of parameter names for this action parameter
          items:
            type: string
      required:
        - name
        - parameters
    ModelState:
      title: State
      type: object
      description: Definition of a particular state
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the state, in capital letters with underscores
        display:
          type: string
          description: Human-readable state name
        desc:
          type: string
          description: Description of the state, e.g., what situation is modelled by the state
        side:
          type: string
          description: Indicates which side of the request the state belongs to
          enum:
            - REQUESTER
            - SUPPLIER
        initial:
          type: boolean
          description: Indicates if the state is the initial state of the request
          default: false
        primaryAction:
          type: string
          description: Name of the primary action for this state.
            Must be one of the actions defined in the actions array and is only meaningful when actions is present.
        editable:
          type: boolean
          description: Indicates that patron request can be updated in this state
        actions:
          type: array
          description: List of all actions that may be performed on the request when in this state
          items:
            $ref: '#/components/schemas/ModelAction'
        events:
          type: array
          description: List of all events that may be triggered to the request when in this state
          items:
            $ref: '#/components/schemas/ModelEvent'
        terminal:
          type: boolean
          description: Indicates if the state is terminal (meaning no actions or events are allowed in this state)
        manualClose:
          type: boolean
          description: Indicates that this terminal state is the target for manual termination
        needsAttention:
          type: boolean
          description: Indicates that this state requires user attention (e.g. displayed as a flag in the UI)
      oneOf:
        - anyOf:
          - required:
            - actions
          - required:
            - events
        - required:
          - terminal
      required:
        - name
        - side

    ModelAction:
      type: object
      title: Action
      additionalProperties: false
      description: Declares an action available while in this state.
      properties:
        name:
          type: string
          description: Name of the action
        desc:
          type: string
          description: Description of the action
        trigger:
          type: string
          description: Trigger for the action
          enum:
            - auto
            - manual
          default: manual
        transitions:
          type: object
          description: Action outcome to state transition mapping. When no transition is defined, the action is considered to be non-state-changing.
          additionalProperties: false
          properties:
            success:
              type: string
              description: Target state when the action succeeds.
            failure:
              type: string
              description: Target state when the action fails.
            review:
              type: string
              description: Target state when the action requires review.
        params:
          type: object
          description: Parameters for the action. The presence of parameters indicates that the action requires additional input to be executed.
          additionalProperties: true
          properties:
            sendTo:
              type: array
              description: Notification recipients for this action.
              items:
                type: string
                enum:
                  - patron
                  - staff
            templateLabel:
              type: string
              description: Template label for this action. The template selector is used to select the appropriate template for generating messages.
      required:
        - name

    ModelEvent:
      type: object
      title: Event
      additionalProperties: false
      description: Declares an event considered for transition while in this state.
      properties:
        name:
          type: string
          description: Name of the event
        desc:
          type: string
          description: Description of the event
        transition:
          type: string
          description: State transition after event has occurred. When no transition is defined, the event is considered to be non-state-changing.
      required:
        - name

    PrItem:
      type: object
      title: Item
      description: Patron request item
      properties:
        id:
          type: string
          description: Item system id
        barcode:
          type: string
          description: Item barcode
        title:
          type: string
          description: Item title
        callNumber:
          type: string
          description: Item call number
        itemId:
          type: string
          description: Item item id
        createdAt:
          type: string
          format: date-time
          description: Item creation date time
      required:
        - id
        - barcode
        - createdAt

    PrNotifications:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of patron request notifications
          items:
            $ref: '#/components/schemas/PrNotification'

    PrItems:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of patron request items
          items:
            $ref: '#/components/schemas/PrItem'

    PrNotification:
      type: object
      title: Notification
      description: Patron request notification
      properties:
        id:
          type: string
          description: Notification id
        fromSymbol:
          type: string
          description: Symbol of notification sender
        toSymbol:
          type: string
          description: Symbol of notification receiver
        direction:
          type: string
          description: Direction of the notification, either sent or received
        kind:
          type: string
          description: Kind of notification, either note or condition
          enum:
            - note
            - condition
        note:
          type: string
          description: Note of notification
        cost:
          type: number
          format: double
          description: Cost amount
        currency:
          type: string
          description: Currency symbol
        condition:
          type: string
          description: Condition of notification
        receipt:
          type: string
          description: Receipt of notification
        createdAt:
          type: string
          format: date-time
          description: Notification creation date time
        acknowledgedAt:
          type: string
          format: date-time
          description: Notification acknowledged at date time
      required:
        - id
        - fromSymbol
        - toSymbol
        - direction
        - kind
        - createdAt

    CreatePrNotification:
      type: object
      title: Create Notification
      description: Create patron request notification body
      properties:
        note:
          type: string
          description: Note of notification
      required:
        - note

    UpdateNotificationReceipt:
      type: object
      title: Update notification receipt
      description: Update notification receipt body
      properties:
        receipt:
          type: string
          description: Notification receipt status
          enum:
            - ACCEPTED
            - REJECTED
            - SEEN
            - SENT
            - FAILED_TO_SEND
      required:
        - receipt

    PullSlip:
      type: object
      title: Pull Slip
      description: A generated pull slip record
      properties:
        id:
          type: string
          description: Pull slip ID
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        generatedAt:
          type: string
          format: date-time
          description: When the PDF was generated
        type:
          type: string
          description: Pull slip type (single, batch)
          enum:
            - single
            - batch
        owner:
          type: string
          description: Symbol of the owning institution
        searchCriteria:
          type: string
          description: Criteria used to generate this pull slip
        pdfLink:
          type: string
          description: Link to download the PDF
      required:
        - id
        - createdAt
        - type
        - owner
        - searchCriteria

    BatchActionName:
      type: string
      description: Name of the batch action to run
      enum:
        - email-pullslips
        - request-aging

    BatchAction:
      type: object
      title: Batch Action
      description: A scheduled batch action
      properties:
        id:
          type: string
          description: Unique identifier of the batch action
        schedule:
          type: string
          description: RRULE schedule expression, e.g. "FREQ=WEEKLY;BYDAY=MO;BYHOUR=6;BYMINUTE=0" (every Monday at 06:00)
        actionName:
          $ref: '#/components/schemas/BatchActionName'
        title:
          type: string
          description: Title of the batch action, for display purposes
        batchQuery:
          type: string
          description: Batch action selection query in CQL format
        actionParams:
          type: object
          description: Parameters for the batch action. For request-aging, interval is required and must be a Go duration string such as "24h" or "168h". Additional parameters are passed to the generated patron-request background action.
          additionalProperties: true
        nextRun:
          type: string
          format: date-time
          description: Next execution time according to the schedule
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        active:
          type: boolean
          description: Indicates if the batch action is active
      required:
        - id
        - schedule
        - actionName
        - createdAt
        - batchQuery
        - active

    BatchActions:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of batch actions
          items:
            $ref: '#/components/schemas/BatchAction'

    CreateBatchAction:
      type: object
      title: Create Batch Action
      description: Request body for creating a batch action
      properties:
        schedule:
          type: string
          description: RRULE schedule expression, e.g. "FREQ=WEEKLY;BYDAY=MO;BYHOUR=6;BYMINUTE=0" (every Monday at 06:00)
        actionName:
          $ref: '#/components/schemas/BatchActionName'
        title:
          type: string
          description: Title of the batch action, for display purposes
        batchQuery:
          type: string
          description: Batch action selection query in CQL format
        actionParams:
          type: object
          description: Parameters for the batch action. For request-aging, interval is required and must be a Go duration string such as "24h" or "168h". Additional parameters are passed to the generated patron-request background action.
          additionalProperties: true
      required:
        - schedule
        - actionName
        - batchQuery

    UpdateBatchAction:
      type: object
      title: Update Batch Action
      description: Request body for updating a batch action
      properties:
        title:
          type: string
          description: Title of the batch action, for display purposes
        schedule:
          type: string
          description: RRULE schedule expression, e.g. "FREQ=WEEKLY;BYDAY=MO;BYHOUR=6;BYMINUTE=0" (every Monday at 06:00)
        batchQuery:
          type: string
          description: Batch action selection query in CQL format
        actionParams:
          type: object
          description: Parameters for the batch action
          additionalProperties: true
      required:
        - schedule
        - batchQuery

    CreatePullSlip:
      type: object
      title: Create Pull Slip
      description: Create pull slip body. If both illTransactionIds and cql are provided, illTransactionIds will be used for pull slip generation and cql will be ignored.
      properties:
        illTransactionIds:
          type: array
          description: Patron request IDs to create pull slips for
          items:
            type: string
        cql:
          description: CQL search for patron requests to create pull slips for
          type: string

    BibliographicInfo:
      type: object
      description: Bibliographic information for an ILL request item, as defined in ISO18626

    TemplatePurpose:
      type: string
      description: Purpose of the template
      enum:
        - email
        - pullslip

    TemplateContentType:
      type: string
      description: Output content type for the template body
      enum:
        - text
        - html

    TemplateAudience:
      type: string
      description: Intended audience for the template. Omit to apply to both patron and staff.
      enum:
        - patron
        - staff

    Template:
      type: object
      title: Template
      description: An email or pull slip template with optional placeholder support
      properties:
        id:
          type: string
          description: Unique identifier of the template
        title:
          type: string
          description: Human-readable title for the template
        purpose:
          $ref: '#/components/schemas/TemplatePurpose'
        subject:
          type: string
          description: Subject line template, supports {{x}} placeholders. Not used for pullslip templates.
        body:
          type: string
          description: Body of the email or pull slip template. Supports {{x}} placeholders.
        contentType:
          $ref: '#/components/schemas/TemplateContentType'
        labels:
          type: array
          description: Predefined labels identifying the template's usage context. Values correspond to templateLabel parameters used in state model send-email actions.
          items:
            type: string
        audience:
          $ref: '#/components/schemas/TemplateAudience'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the template was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the template was last updated
      required:
        - id
        - title
        - purpose
        - body
        - contentType
        - labels
        - createdAt

    Templates:
      type: object
      required:
        - items
        - about
      properties:
        about:
          $ref: '#/components/schemas/About'
        items:
          type: array
          description: List of templates
          items:
            $ref: '#/components/schemas/Template'

    CreateTemplate:
      type: object
      title: Create Template
      description: Request body for creating a template
      properties:
        title:
          type: string
          description: Human-readable title for the template
        purpose:
          $ref: '#/components/schemas/TemplatePurpose'
        subject:
          type: string
          description: Subject line template, supports {{x}} placeholders. Not used for pullslip templates.
        body:
          type: string
          description: Body of the email or pull slip template. Supports {{x}} placeholders.
        contentType:
          $ref: '#/components/schemas/TemplateContentType'
        labels:
          type: array
          description: Labels identifying the template's usage context
          items:
            type: string
        audience:
          $ref: '#/components/schemas/TemplateAudience'
      required:
        - title
        - purpose
        - body
        - contentType
        - labels

    UpdateTemplate:
      type: object
      title: Update Template
      description: Request body for updating a template
      properties:
        title:
          type: string
          description: Human-readable title for the template
        subject:
          type: string
          description: Subject line template, supports {{x}} placeholders. Not used for pullslip templates.
        body:
          type: string
          description: Body of the email or pull slip template. Supports {{x}} placeholders.
        contentType:
          $ref: '#/components/schemas/TemplateContentType'
        labels:
          type: array
          description: Labels identifying the template's usage context
          items:
            type: string
        audience:
          $ref: '#/components/schemas/TemplateAudience'
      required:
        - title
        - body
        - contentType
        - labels

paths:
  /:
    get:
      summary: Retrieve index information
      responses:
        '200':
          description: Successful retrieval of index information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events:
    get:
      summary: Retrieve events
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/RequesterRequestId'
        - $ref: '#/components/parameters/IllTransactionId'
        - $ref: '#/components/parameters/RequesterSymbol'
      responses:
        '200':
          description: Successful retrieval of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ill_transactions/{id}:
    get:
      summary: Get an ILL transaction by ID
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/RequesterSymbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the ILL transaction to retrieve
      responses:
        '200':
          description: Successful retrieval of the ILL transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IllTransaction'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. ILL transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete an ILL transaction by ID
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the ILL transaction to delete
      responses:
        '204':
          description: ILL transaction deleted successfully (No Content)
        '404':
          description: ILL transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ill_transactions:
    get:
      summary: Get all ILL transactions
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/RequesterRequestId'
        - $ref: '#/components/parameters/RequesterSymbol'
        - $ref: '#/components/parameters/Cql'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful retrieval of the ILL transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IllTransactions'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden. Invalid tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /peers:
    get:
      summary: Get all peers
      parameters:
        - $ref: '#/components/parameters/Cql'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful retrieval of peers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peers'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new peer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Peer'
      responses:
        '201':
          description: Peer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peer'
        '400':
          description: Bad request (e.g., invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /peers/{id}:
    get:
      summary: Get a peer by ID
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the peer to retrieve
      responses:
        '200':
          description: Successful retrieval of the peer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peer'
        '404':
          description: Peer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a peer
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the peer to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Peer'
      responses:
        '200':
          description: Peer updated successfully
        '400':
          description: Bad request (e.g., invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Peer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a peer
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the peer to delete
      responses:
        '204':
          description: Peer deleted successfully (No Content)
        '404':
          description: Peer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /located_suppliers:
    get:
      summary: Retrieve located suppliers
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/RequesterRequestId'
        - $ref: '#/components/parameters/IllTransactionId'
        - $ref: '#/components/parameters/RequesterSymbol'
      responses:
        '200':
          description: Successful retrieval of located suppliers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocatedSuppliers'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /archive_ill_transactions:
    post:
      summary: Trigger ILL Transaction archive process
      parameters:
        - $ref: '#/components/parameters/ArchiveDelay'
        - $ref: '#/components/parameters/ArchiveStatus'
      responses:
        '200':
          description: Process started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusMessage'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /patron_requests:
    get:
      summary: Retrieve patron requests
      description: |
        Use this endpoint to retrieve patron requests.
        Query parameter cql can be used to filter the results.
        With cql you can use these fields id, state, side, requester_name, requester_symbol,
        supplier_name, supplier_symbol, needs_attention, has_notification, has_cost,
        has_unread_notification, service_type, service_level, created_at, needed_at, requester_req_id,
        title, author, patron, terminal_state, updated_at, isbn, issn, given_name, surname, has_internal_note,
        cql.serverChoice.
      tags:
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/RequesterRequestId'
        - $ref: '#/components/parameters/RequesterSymbol'
        - $ref: '#/components/parameters/Cql'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
        - $ref: '#/components/parameters/Facets'
      responses:
        '200':
          description: Successful retrieval of patron requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatronRequests'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new patron request
      tags:
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePatronRequest'
      responses:
        '201':
          description: Patron request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatronRequest'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}:
    get:
      summary: Get a patron request by ID
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request to retrieve
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Successful retrieval of the patron request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatronRequest'
        '404':
          description: Patron request not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a patron request
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request to update
        - $ref: '#/components/parameters/Tenant'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePatronRequest'
      responses:
        '200':
          description: Patron request updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatronRequest'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Patron request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a patron request
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request to delete
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '204':
          description: Patron request deleted successfully (No Content)
        '404':
          description: Patron request not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/actions:
    get:
      summary: Get valid actions for patron request in current state
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: List of available actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowedActions'
        '404':
          description: Patron request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: There was internal server error looking up patron request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/action:
    post:
      summary: Execute action for given patron request
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteAction'
      responses:
        '200':
          description: List of available actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResult'

        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Patron request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: There was internal server error looking up patron request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/terminate:
    post:
      summary: Manually terminate a patron request
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Termination action result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResult'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Patron request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: There was internal server error terminating patron request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/events:
    get:
      summary: Retrieve patron request related events
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      tags:
        - patron-requests-api
      responses:
        '200':
          description: Successful retrieval of patron request events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/items:
    get:
      summary: Retrieve patron request related items
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      tags:
        - patron-requests-api
      responses:
        '200':
          description: Successful retrieval of patron request items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrItems'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/notifications:
    get:
      summary: Retrieve patron request related notifications
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
        - $ref: '#/components/parameters/NotificationKind'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      tags:
        - patron-requests-api
      responses:
        '200':
          description: Successful retrieval of patron request notifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrNotifications'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create patron request notification
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      tags:
        - patron-requests-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrNotification'
      responses:
        '201':
          description: Patron request notification created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrNotification'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/notifications/{notificationId}/receipt:
    put:
      summary: Update patron request notification receipt
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - in: path
          name: notificationId
          schema:
            type: string
          required: true
          description: ID of the notification
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      tags:
        - patron-requests-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationReceipt'
      responses:
        '204':
          description: Patron request notification updated successfully
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /patron_requests/{id}/internal_note:
    put:
      summary: Update the staff-only internal note on a patron request
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the patron request
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInternalNote'
      responses:
        '204':
          description: Internal note updated successfully (No Content)
        '400':
          description: Bad Request. Invalid or missing body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found. Patron request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sse/events:
    get:
      summary: Subscribe to real-time notifications. Notification is send out every time when ISO18626 message is sent out
      description: |
        Opens an SSE stream.
        Each `data:` payload is a JSON object with the same structure as `SseResult` (`event` and `data`).
      tags:
        - sse-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Side'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Result of subscription
          content:
            text/event-stream:
              schema:
                type: string
              example: |
                event: message-requester
                data: {"event":"message-requester","data":{"supplyingAgencyMessage":{"header":{"requestingAgencyId":{"agencyIdType":{"text":"ISIL"},"agencyIdValue":"REQ"}}}}}

        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /state_model/models/{model}:
    get:
      summary: Retrieve a state model by name
      tags:
        - patron-requests-api
      parameters:
        - in: path
          name: model
          schema:
            type: string
          required: true
          description: The name of the statemodel to retrieve
        - $ref: '#/components/parameters/Tenant'
      responses:
        '200':
          description: Successful retrieval of state model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateModel'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /state_model/capabilities:
    get:
      summary: Retrieve built-in state model capabilities
      tags:
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
      responses:
        '200':
          description: Successful retrieval of state model capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateModelCapabilities'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /state_model/batch_actions:
    get:
      summary: Retrieve batch actions defaults for built-in state models
      tags:
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
      responses:
        '200':
          description: Successful retrieval of batch actions defaults
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreateBatchAction'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /batch_actions:
    get:
      summary: List all batch actions
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful retrieval of batch actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchActions'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new batch action
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchAction'
      responses:
        '201':
          description: Batch action created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAction'
        '400':
          description: Bad Request. Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /batch_actions/{id}:
    get:
      summary: Get a batch action by ID
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the batch action to retrieve
      responses:
        '200':
          description: Batch action retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAction'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Batch action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a batch action by ID
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the batch action to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBatchAction'
      responses:
        '200':
          description: Batch action updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAction'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Batch action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a batch action by ID
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the batch action to delete
      responses:
        '204':
          description: Batch action deleted successfully (No Content)
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Batch action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /batch_actions/{id}/disable:
    post:
      summary: Disable a batch action by ID
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the batch action to disable
      responses:
        '204':
          description: Batch action disabled successfully (No Content)
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Batch action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /batch_actions/{id}/enable:
    post:
      summary: Enable a batch action by ID
      tags:
        - scheduler-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the batch action to enable
      responses:
        '204':
          description: Batch action enabled successfully (No Content)
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Batch action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /pullslips/{id}:
    get:
      summary: Get pull slip by ID
      tags:
        - pull-slips-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the pull slip to retrieve
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Pull slip retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullSlip'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pull slip not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /pullslips/{id}/pdf:
    get:
      summary: Download pull slip PDF by ID
      tags:
        - pull-slips-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the pull slip whose PDF to download
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Pull slip PDF retrieved successfully
          headers:
            Content-Disposition:
              description: Attachment filename for the PDF
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pull slip not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /pullslips:
    post:
      summary: Create pull slip for a patron request
      tags:
        - pull-slips-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePullSlip'
      responses:
        '200':
          description: Pull slip PDF generated successfully
          headers:
            Content-Disposition:
              description: Attachment filename for the generated PDF
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /pullslips/{id}/regenerate:
    post:
      summary: Regenerate pull slip PDF by ID
      tags:
        - pull-slips-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the pull slip whose PDF to regenerate
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Pull slip PDF regenerated successfully
          headers:
            Content-Disposition:
              description: Attachment filename for the PDF
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pull slip not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /templates:
    get:
      summary: List all templates
      tags:
        - templates-api
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful retrieval of templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Templates'
        '400':
          description: Bad Request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new template
      tags:
        - templates-api
        - patron-requests-api
      parameters:
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplate'
      responses:
        '201':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Bad Request. Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /templates/{id}:
    get:
      summary: Get a template by ID
      tags:
        - templates-api
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the template to retrieve
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a template by ID
      tags:
        - templates-api
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the template to update
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplate'
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Bad Request. Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a template by ID
      tags:
        - templates-api
        - patron-requests-api
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID of the template to delete
        - $ref: '#/components/parameters/Tenant'
        - $ref: '#/components/parameters/Symbol'
      responses:
        '204':
          description: Template deleted successfully (No Content)
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'