openapi: 3.0.3
info:
  title: LUX Yale Collections Discovery API
  description: >-
    Public read API for LUX, Yale's cross-collection discovery platform providing
    unified access to more than 41 million records across Yale's museums, archives
    and library collections. Entities are served as Linked Art JSON-LD. This
    description documents the public middle-tier endpoints exposed under
    https://lux.collections.yale.edu and was derived from the open-source LUX
    backend API usage documentation and Postman collection
    (github.com/project-lux/lux-marklogic) and confirmed against live responses.
    Only the public read endpoints are described here; write/admin endpoints from
    the backend custom API are intentionally omitted.
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: LUX Yale Collections Discovery
    url: https://lux.collections.yale.edu/content/technology
servers:
  - url: https://lux.collections.yale.edu
    description: LUX public production
tags:
  - name: Search
    description: Search and discovery across LUX scopes
  - name: Facets
    description: Faceted aggregation over search results
  - name: Related
    description: Related entity discovery
  - name: Configuration
    description: Search configuration metadata
  - name: Documents
    description: Linked Art JSON-LD document retrieval
paths:
  /api/search/{scope}:
    get:
      tags: [Search]
      operationId: search
      summary: Search a scope
      description: >-
        Executes a query within a scope and returns a Linked Art
        OrderedCollectionPage of matching results in JSON-LD. The query may be
        expressed in LUX JSON Grammar or LUX String Grammar.
      parameters:
        - $ref: '#/components/parameters/Scope'
        - name: q
          in: query
          required: true
          description: Search criteria in LUX JSON Grammar or String Grammar.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageLength
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
        - name: sort
          in: query
          required: false
          description: Sort specification.
          schema:
            type: string
        - name: filterResults
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A page of search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderedCollectionPage'
        '400':
          description: Malformed query.
  /api/search-estimate/{scope}:
    get:
      tags: [Search]
      operationId: searchEstimate
      summary: Estimate result count
      description: >-
        Returns a Linked Art OrderedCollection containing the totalItems count of
        unfiltered results matching the query, without retrieving full documents.
      parameters:
        - $ref: '#/components/parameters/Scope'
        - name: q
          in: query
          required: true
          description: Search criteria in LUX JSON Grammar.
          schema:
            type: string
      responses:
        '200':
          description: Result count estimate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderedCollection'
        '400':
          description: Malformed query.
  /api/facets/{scope}:
    get:
      tags: [Facets]
      operationId: facets
      summary: Retrieve facet values
      description: >-
        Returns an OrderedCollectionPage of facet values and their occurrence
        counts for a named facet over a query.
      parameters:
        - $ref: '#/components/parameters/Scope'
        - name: name
          in: query
          required: true
          description: Facet name.
          schema:
            type: string
        - name: q
          in: query
          required: true
          description: Search criteria.
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: pageLength
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Facet values with counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderedCollectionPage'
  /api/related-list/{scope}:
    get:
      tags: [Related]
      operationId: relatedList
      summary: Retrieve related entities
      description: >-
        Returns an OrderedCollectionPage listing documents related to a given URI
        through various relationship types.
      parameters:
        - $ref: '#/components/parameters/Scope'
        - name: name
          in: query
          required: true
          description: Related list name.
          schema:
            type: string
        - name: uri
          in: query
          required: true
          description: URI of the entity whose relations are requested.
          schema:
            type: string
            format: uri
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Related entities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderedCollectionPage'
  /api/advanced-search-config:
    get:
      tags: [Configuration]
      operationId: advancedSearchConfig
      summary: Fetch advanced search configuration
      description: >-
        Returns the advanced search configuration describing searchable terms by
        scope, search options and stop words.
      responses:
        '200':
          description: Advanced search configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedSearchConfig'
  /data/{type}/{id}:
    get:
      tags: [Documents]
      operationId: getDocument
      summary: Retrieve a Linked Art document
      description: >-
        Retrieves a single entity as a Linked Art JSON-LD document by its type and
        identifier.
      parameters:
        - name: type
          in: path
          required: true
          description: Entity type segment (e.g. object, work, person, group, place, concept, set, event).
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: Entity identifier (UUID).
          schema:
            type: string
      responses:
        '200':
          description: A Linked Art JSON-LD document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedArtEntity'
        '404':
          description: Document not found.
components:
  parameters:
    Scope:
      name: scope
      in: path
      required: true
      description: >-
        The discovery scope to query. LUX scopes map to the major Linked Art
        entity categories.
      schema:
        type: string
        enum: [item, work, agent, place, concept, set, event]
  schemas:
    OrderedCollection:
      type: object
      description: A Linked Art OrderedCollection summarizing a result set.
      properties:
        '@context':
          type: string
          format: uri
        id:
          type: string
          format: uri
        type:
          type: string
          example: OrderedCollection
        label:
          $ref: '#/components/schemas/LanguageMap'
        summary:
          $ref: '#/components/schemas/LanguageMap'
        totalItems:
          type: integer
        first:
          $ref: '#/components/schemas/CollectionPageRef'
        last:
          $ref: '#/components/schemas/CollectionPageRef'
      required: [id, type, totalItems]
    OrderedCollectionPage:
      type: object
      description: A single page of a Linked Art OrderedCollection.
      properties:
        '@context':
          type: string
          format: uri
        id:
          type: string
          format: uri
        type:
          type: string
          example: OrderedCollectionPage
        partOf:
          $ref: '#/components/schemas/OrderedCollection'
        orderedItems:
          type: array
          items:
            $ref: '#/components/schemas/EntityRef'
        next:
          $ref: '#/components/schemas/CollectionPageRef'
        prev:
          $ref: '#/components/schemas/CollectionPageRef'
      required: [id, type, orderedItems]
    CollectionPageRef:
      type: object
      properties:
        id:
          type: string
          format: uri
        type:
          type: string
          example: OrderedCollectionPage
      required: [id]
    EntityRef:
      type: object
      description: A reference to a LUX entity returned within search results.
      properties:
        id:
          type: string
          format: uri
        type:
          type: string
          example: HumanMadeObject
      required: [id, type]
    LanguageMap:
      type: object
      description: >-
        A Linked Art language map: keys are language tags and values are arrays of
        strings.
      additionalProperties:
        type: array
        items:
          type: string
    AdvancedSearchConfig:
      type: object
      description: Advanced search configuration metadata.
      properties:
        terms:
          type: object
          description: Searchable terms organized by scope.
        options:
          type: object
          description: Allowed and default search options.
        stopWords:
          type: array
          items:
            type: string
      required: [terms, options]
    LinkedArtEntity:
      type: object
      description: >-
        A Linked Art JSON-LD entity document. Fields follow the CIDOC-CRM derived
        Linked Art model; common fields are listed but additional properties are
        permitted.
      properties:
        '@context':
          type: string
          format: uri
        id:
          type: string
          format: uri
        type:
          type: string
          example: HumanMadeObject
        _label:
          type: string
        identified_by:
          type: array
          items:
            type: object
        classified_as:
          type: array
          items:
            type: object
        referred_to_by:
          type: array
          items:
            type: object
        member_of:
          type: array
          items:
            type: object
        equivalent:
          type: array
          items:
            type: object
        subject_of:
          type: array
          items:
            type: object
        representation:
          type: array
          items:
            type: object
        shows:
          type: array
          items:
            type: object
        dimension:
          type: array
          items:
            type: object
        _links:
          type: object
      required: [id, type]
      additionalProperties: true