FOLIO Admin API

openapi: 3.2.0
info:
  title: Folio Admin API
  version: '1.0'
  description: 'Operations tagged Admin across 6 of this provider''s published API definitions: folio-mod-agreements-openapi.json, folio-mod-licenses-openapi.json, folio-mod-linked-data-openapi.json, folio-mod-agreements-openapi.yml, folio-mod-licenses-openapi.yml, folio-mod-linked-data-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://folio-snapshot-okapi.dev.folio.org
- url: https://folio-snapshot-2-okapi.dev.folio.org
- url: https://folio-etesting-snapshot-kong.ci.folio.org
tags:
- name: Admin
paths:
  /erm/admin/loadPackage:
    get:
      tags:
      - Admin
      summary: Upload and upsert a package file
      description: Developer helper for uploading a package JSON file directly (e.g. via curl) rather than through the normal harvest pipeline. If no package_file part is present, or it fails to bind, the response body is empty
      operationId: getAdminLoadPackage
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                package_file:
                  type: string
                  format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageIngestResult'
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerCacheUpdate:
    get:
      tags:
      - Admin
      summary: Trigger an update of the remote KB package cache
      operationId: getAdminTriggerCacheUpdate
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK -- returns no response body
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/pullPackage:
    post:
      tags:
      - Admin
      summary: Queue a one-time OAI-PMH harvest of an enabled package
      description: Requires Harvest ingress mode and an existing tenant-local package with Harvest ingress metadata pointing to an active GOKB OAI package source. The source and GOKB UUID are derived from the package; callers cannot supply a source URL. Explicitly paused packages are rejected; a legacy null synchronization flag is treated as enabled. Duplicate queued or running pulls are rejected. Returns a background job ID; inspect GET /erm/jobs/{jobId} for completion and errors. If the source is being harvested, the same job returns to Queued and retries on later job-runner ticks without occupying a worker. Each attempt rechecks synchronization state before fetching. It fetches GetRecord with metadataPrefix=gokb and applies the same package eligibility rules as bulk harvesting. Neither the synchronization setting nor the RemoteKB cursor or lastCheck is changed. Missing, deleted, ineligible or invalid upstream records fail the job without ingesting contents.
      operationId: postAdminPullPackage
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - packageId
              properties:
                packageId:
                  type: string
                  format: uuid
                  description: Tenant-local package ID, not the GOKB UUID
      responses:
        '202':
          description: Package pull queued
          headers:
            Location:
              description: URL of the background job
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - jobId
                properties:
                  jobId:
                    type: string
                    format: uuid
        '400':
          description: Missing or invalid packageId
        '403':
          description: Forbidden
        '404':
          description: Package not found in this tenant
        '409':
          description: Paused package, unsupported mode or source, missing identifier, or duplicate pull
        '500':
          description: Internal server error
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerSync:
    get:
      tags:
      - Admin
      summary: Trigger a remote KB harvest sync
      operationId: getAdminTriggerSync
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerActivationUpdate:
    get:
      tags:
      - Admin
      summary: Trigger an activation update of the remote KB package cache
      operationId: getAdminTriggerActivationUpdate
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Currently always an empty object -- no status field is set
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerHousekeeping:
    get:
      tags:
      - Admin
      summary: Trigger ERM housekeeping
      description: Also run automatically every 24 hours via Okapi's timer interface
      operationId: getAdminTriggerHousekeeping
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerEntitlementLogUpdate:
    get:
      tags:
      - Admin
      summary: Trigger an update of the entitlement log
      operationId: getAdminTriggerEntitlementLogUpdate
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerDocMigration:
    get:
      tags:
      - Admin
      summary: Trigger migration of uploaded documents to object storage
      description: Migrates uploaded file attachments still stored in the Postgres database (LOB) to the configured S3/MinIO object store
      operationId: getAdminTriggerDocMigration
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /erm/admin/triggerEntitlementEholdings:
    get:
      tags:
      - Admin
      summary: Trigger an eHoldings entitlement sync
      description: Also run automatically every hour via Okapi's timer interface, which never sets force, always honouring the entitlement sync buffer window
      operationId: getAdminTriggerEntitlementEholdings
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      - in: query
        name: force
        description: Bypass the entitlement sync buffer window
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '400':
          description: Bad request error
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /licenses/admin/triggerHousekeeping:
    get:
      tags:
      - Admin
      summary: Trigger license housekeeping
      description: Runs the license housekeeping service. This sets `endDateSemantics` on any records where it is unset, and deletes any Organisation records no longer linked to a license.
      operationId: getLicensesAdminTriggerHousekeeping
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
      x-operation-id-source: normalized
      x-operation-id-original: getAdminTriggerHousekeeping
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /licenses/admin/triggerDocMigration:
    get:
      tags:
      - Admin
      summary: Trigger migration of uploaded documents to object storage
      description: Migrates uploaded license document (LOB) attachments still stored in the Postgres database to the configured S3/MinIO object store.
      operationId: getLicensesAdminTriggerDocMigration
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrailsErrorResponse'
      security:
      - accessToken: []
      - okapiToken: []
      x-operation-id-source: normalized
      x-operation-id-original: getAdminTriggerDocMigration
    servers:
    - url: https://folio-snapshot-okapi.dev.folio.org
    - url: https://folio-snapshot-2-okapi.dev.folio.org
    - url: https://folio-etesting-snapshot-kong.ci.folio.org
  /linked-data/admin/caches:
    delete:
      operationId: clearCaches
      tags:
      - Admin
      description: Clear all application caches
      responses:
        '204':
          description: Application caches cleared
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Clear caches
      x-summary-source: derived
components:
  schemas:
    PackageIngestResult:
      type: object
      properties:
        startTime:
          type: integer
        updateTime:
          type: integer
        packageId:
          type: string
          format: uuid
        titleCount:
          type: integer
        newTitles:
          type: integer
        removedTitles:
          type: integer
        updatedTitles:
          type: integer
        updatedAccessStart:
          type: integer
        updatedAccessEnd:
          type: integer
    GrailsErrorResponse:
      type: object
      description: Error-handler body for an uncaught exception raised during request processing. `exception` and `stackTrace` usually suppressed in production systems
      required:
      - error
      - timestamp
      - message
      properties:
        error:
          type: integer
          description: HTTP status code
        timestamp:
          type: string
          format: date-time
        message:
          type: string
        exception:
          type: string
          description: Exception class and message.
        stackTrace:
          type: array
          items:
            type: string
    parameter:
      description: List of key/value parameters of an error
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
    error:
      description: An error
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: object
          description: Error message parameters
          $ref: '#/components/schemas/parameters'
    errors:
      description: A set of errors
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        errors:
          description: List of errors
          id: errors
          type: array
          items:
            type: object
            $ref: '#/components/schemas/error'
        total_records:
          description: Total number of errors
          type: integer
    parameters:
      description: List of key/value parameters of an error
      $schema: http://json-schema.org/draft-04/schema#
      type: array
      items:
        type: object
        $ref: '#/components/schemas/parameter'
  parameters:
    x-okapi-tenant:
      in: header
      name: x-okapi-tenant
      required: true
      schema:
        type: string
  responses:
    internalServerErrorResponse:
      description: When unhandled exception occurred during code execution, e.g. NullPointerException
      content:
        application/json:
          example: example/unknownError.sample
          schema:
            $ref: '#/components/schemas/errors'
  securitySchemes:
    okapiToken:
      type: apiKey
      in: header
      name: x-okapi-token
    accessToken:
      type: apiKey
      in: cookie
      name: folioAccessToken
x-refined-from:
- folio-mod-agreements-openapi.json
- folio-mod-licenses-openapi.json
- folio-mod-linked-data-openapi.json
- folio-mod-agreements-openapi.yml
- folio-mod-licenses-openapi.yml
- folio-mod-linked-data-openapi.yml