openapi: 3.0.3
info:
  title: Lund University Publications (LUP) Search API
  description: >-
    REST/JSON(P) search interface over the Lund University Publications (LUP)
    database. Returns publication hits with paging metadata (total, size, start,
    limit). Individual records can also be exported in bibliographic formats.
    No authentication is required. The public API only returns records with
    status 'public'. This OpenAPI description was reconstructed faithfully from
    the published LUP API documentation (https://lup.lub.lu.se/search/doc/api),
    the published publication JSON Schema
    (https://lup.lub.lu.se/search/schema/publication.json), and observed live
    responses; LUP does not publish a native OpenAPI/Swagger document.
  version: '1.0'
  contact:
    name: Lund University Libraries
    url: https://lup.lub.lu.se/search/doc/api
  license:
    name: See LUP terms of use
    url: https://lup.lub.lu.se/search/doc/api
servers:
  - url: https://lup.lub.lu.se/search
    description: Lund University Publications search service
paths:
  /publication:
    get:
      operationId: searchPublications
      summary: Search publications
      description: >-
        Full-text and field search over LUP publications. Supports CQL-style
        queries via the q parameter, paging, sorting, and JSON or JSONP output.
      parameters:
        - name: q
          in: query
          description: Search query (free text or CQL expression).
          required: false
          schema:
            type: string
          example: dna
        - name: format
          in: query
          description: Response format.
          required: false
          schema:
            type: string
            enum: [json, jsonp]
            default: json
        - name: callback
          in: query
          description: JSONP callback function name (used when format=jsonp).
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Comma-separated sort keys with .asc or .desc direction, e.g.
            year.desc,title.asc.
          required: false
          schema:
            type: string
          example: year.desc,title.asc
        - name: start
          in: query
          description: Zero-based pagination offset of the first returned hit.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          description: Maximum number of hits to return per request.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 10
      responses:
        '200':
          description: A page of publication search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /publication/{id}:
    get:
      operationId: getPublication
      summary: Retrieve or export a single publication
      description: >-
        Retrieve a single publication by its LUP id. Use the format query
        parameter (or a format file extension on the path) to export the record
        in a bibliographic format.
      parameters:
        - name: id
          in: path
          required: true
          description: Unique LUP publication id.
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Export/serialization format for the record.
          schema:
            type: string
            enum: [json, jsonp, xls, xls2, csv, csv2, bibtex, ris, enw]
            default: json
      responses:
        '200':
          description: The requested publication record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publication'
            text/plain:
              schema:
                type: string
        '404':
          description: No publication found for the given id.
components:
  schemas:
    SearchResult:
      type: object
      description: A page of publication search results.
      properties:
        total:
          type: integer
          description: Total number of publications matching the query.
        size:
          type: integer
          description: Number of hits actually returned in this page.
        start:
          type: integer
          description: Zero-based offset of the first returned hit.
        limit:
          type: integer
          description: Maximum number of hits requested per page.
        hits:
          type: array
          description: List of publication hits for this page.
          items:
            $ref: '#/components/schemas/PublicationHit'
    PublicationHit:
      type: object
      description: >-
        A publication as returned by the search endpoint. Fields reflect the
        live JSON response shape, which differs from the export/record schema.
      properties:
        _id:
          type: string
        uuid:
          type: string
        mainTitle:
          type: string
        subtitle:
          type: string
        sortTitle:
          type: string
        abstract:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              lang:
                type: string
        type:
          type: string
        documentType:
          type: string
        documentTypeFull:
          type: string
        documentSubtype:
          type: string
        lupType:
          type: string
        lupTypeFull:
          type: string
        lupSubtype:
          type: string
        subject:
          type: array
          items:
            type: string
        keyword:
          type: array
          items:
            type: string
        publication:
          type: string
        publisher:
          type: string
        publishingYear:
          type: string
        publishingDate:
          type: string
        publicationStatus:
          type: string
        submissionStatus:
          type: string
        peerReviewed:
          type: boolean
        openAccess:
          type: integer
        isNonLuPublication:
          type: boolean
        language:
          type: array
          items:
            type: string
        issn:
          type: array
          items:
            type: string
        volume:
          type: string
        issue:
          type: string
        articleNumber:
          type: string
        pagesStart:
          type: string
        pagesEnd:
          type: string
        portalUrl:
          type: string
          format: uri
        doiInfo:
          type: object
        externalIdentifier:
          type: array
          items:
            type: object
        totalNumberOfAuthors:
          type: integer
        author:
          type: array
          items:
            $ref: '#/components/schemas/HitAuthor'
        first_author:
          $ref: '#/components/schemas/HitAuthor'
        last_author:
          $ref: '#/components/schemas/HitAuthor'
        contributor_id:
          type: array
          items:
            type: string
        department:
          type: array
          items:
            type: object
        researchGroup:
          type: array
          items:
            type: object
        record_fulltext_access:
          type: string
        dateCreated:
          type: string
        dateLastChanged:
          type: string
        dateFirstPublic:
          type: string
        dateApproved:
          type: string
        datePureModified:
          type: string
        oai_datestamp:
          type: string
        digest:
          type: string
        additionalInfo:
          type: object
    HitAuthor:
      type: object
      description: An author as returned in a search hit.
      properties:
        fullName:
          type: string
        givenName:
          type: string
        surname:
          type: string
        uuid:
          type: string
        luLdapId:
          type: string
        orcid:
          type: string
        role:
          type: string
        affiliation:
          type: array
          items:
            type: object
            properties:
              name:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                    lang:
                      type: string
              organizationNumber:
                type: string
              isExternal:
                type: integer
    Publication:
      type: object
      description: >-
        A LU publication as defined by the LUP publication JSON Schema
        (https://lup.lub.lu.se/search/schema/publication.json). Used for the
        single-record/export representation.
      required: [_id, type, classification, status, external, title]
      properties:
        _id:
          type: string
          description: unique publication id
        type:
          type: string
          enum: [book, bookChapter, bookEditor, conference, dissertation, journalArticle, licentiateThesis, misc]
        classification:
          type: string
          enum: [A1, A2, A3, A4, B1, B2, B3, C1, C3, D1, D2, P1, V, U]
          description: UGent classification code of publication
        status:
          type: string
          enum: [unsubmitted, submitted, returned, public, pdeleted]
          description: record status (public API only returns 'public')
        publication_status:
          type: string
          enum: [unpublished, submitted, inpress, published]
        external:
          type: integer
          enum: [0, 1]
        title:
          type: string
        alternative_title:
          type: array
          items:
            type: string
        abstract:
          type: array
          items:
            type: string
        keyword:
          type: array
          items:
            type: string
        year:
          type: string
          pattern: '^\d{4}$'
        language:
          type: array
          items:
            type: string
            minLength: 3
            maxLength: 3
        subject:
          type: array
          items:
            type: string
            enum:
              - Agriculture and Food Sciences
              - Arts and Architecture
              - Biology and Life Sciences
              - Business and Economics
              - Chemistry
              - Cultural Sciences
              - Earth and Environmental Sciences
              - General Works
              - History and Archaeology
              - Languages and Literatures
              - Law and Political Science
              - Mathematics and Statistics
              - Medicine and Health Sciences
              - Performing Arts
              - Philosophy and Religion
              - Physics and Astronomy
              - Science General
              - Social Sciences
              - Technology and Engineering
              - Veterinary Sciences
        author:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        editor:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        promoter:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        affiliation:
          type: array
          items:
            $ref: '#/components/schemas/Affiliation'
        parent:
          type: object
          properties:
            title:
              type: string
            short_title:
              type: string
        publisher:
          type: object
          properties:
            location:
              type: string
            name:
              type: string
        volume:
          type: string
        issue:
          type: string
        article_number:
          type: string
        edition:
          type: string
        isbn:
          type: array
          items:
            type: string
        issn:
          type: array
          items:
            type: string
        doi:
          type: array
          items:
            type: string
        wos_id:
          type: string
        file:
          type: array
          items:
            $ref: '#/components/schemas/File'
        jcr:
          $ref: '#/components/schemas/Jcr'
        date_created:
          type: string
        date_updated:
          type: string
        date_submitted:
          type: string
        date_approved:
          type: string
    Person:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
          description: full name, first name first
        name_last_first:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        ugent_id:
          type: array
          items:
            type: string
            pattern: '^\d{12}$'
        affiliation:
          type: array
          items:
            $ref: '#/components/schemas/Affiliation'
    Affiliation:
      type: object
      properties:
        ugent_id:
          type: string
          description: LU organization id
        path:
          type: object
          properties:
            ugent_id:
              type: string
    File:
      type: object
      required: [_id, content_type, name, access]
      properties:
        _id:
          type: string
        content_type:
          type: string
        name:
          type: string
        description:
          type: string
        access:
          type: string
          enum: [openAccess, lu, admin]
        size:
          type: integer
          minimum: 1
    Jcr:
      type: object
      description: Journal Citation Reports info for the publication year.
      properties:
        category_quartile:
          type: integer
          minimum: 1
          maximum: 4
        category_decile:
          type: integer
          minimum: 1
          maximum: 10
        category_vigintile:
          type: integer
          minimum: 1
          maximum: 20
        total_cites:
          type: integer
          minimum: 0
        immediacy_index:
          type: number
          minimum: 0
        impact_factor:
          type: number
          minimum: 0
        impact_factor_5year:
          type: number
          minimum: 0
        eigenfactor:
          type: number
          minimum: 0
        prev_impact_factor:
          type: number
          minimum: 0
        prev_category_quartile:
          type: integer
          minimum: 1
          maximum: 4