openapi: 3.2.0
info:
  title: UC San Diego Library Digital Collections JSON Search API
  description: 'Public, read-only JSON search-and-retrieval interface over the UC San Diego Library Digital Collections (DC), the Library''s locally developed Digital Asset Management System (DAMS). The stack is Fedora-backed and Blacklight/Solr-fronted, and the JSON representations are the same documents that back the public HTML interface — request `.json` on a search or object path and the Solr response is returned directly.

    UC San Diego operates this service itself: `library.ucsd.edu` resolves inside UC San Diego address space (132.239.119.5) and is served from the Library''s own Apache origin, not from a repository vendor''s platform. It is registered on re3data as an institutional data provider (r3d100011577) and mints DOIs under the DataCite repository account CDL.UCSD (prefix 10.6075).

    UC San Diego does NOT publish an OpenAPI description for this interface. This document was written by API Evangelist from live probes of the endpoints and their responses on 2026-08-19; it is a description of observed behaviour, not a contract the institution has committed to.

    Note for automated clients: `library.ucsd.edu` fronts browser-like User-Agent strings with an Anubis proof-of-work bot challenge that returns HTTP 200 with a challenge body. Plain non-browser User-Agents (curl, python-requests) are served normally.'
  version: 2026-08-19
  contact:
    name: UC San Diego Library — Research Data Curation
    email: research-data-curation@ucsd.edu
    url: https://library.ucsd.edu/dc/p/about
  license:
    name: Rights vary per object; see the Digital Collections rights statements
    url: https://library.ucsd.edu/dc/p/collection_policies
servers:
- url: https://library.ucsd.edu
  description: UC San Diego Library Digital Collections (production)
tags:
- name: search
  description: Faceted search across publicly discoverable digital objects and collections.
paths:
  /dc/search.json:
    get:
      tags:
      - search
      summary: Search digital collections
      operationId: searchDigitalCollections
      description: Runs a dismax keyword search across publicly discoverable objects and returns the raw Solr response, including facet counts and highlighting. The service applies a server-side filter of `discover_access_group_ssim:public OR discover_access_group_ssim:unknown`, so restricted and embargoed material is never returned to anonymous clients. `GET /dc/search?format=json` returns the same body.
      parameters:
      - name: q
        in: query
        required: false
        description: Keyword query. Boosted across title, name, subject, scope/content note and full text.
        schema:
          type: string
        example: ocean
      - name: rows
        in: query
        required: false
        description: Number of documents to return in the response page.
        schema:
          type: integer
          minimum: 1
          default: 10
      - name: page
        in: query
        required: false
        description: 1-indexed result page.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: sort
        in: query
        required: false
        description: Solr sort clause, e.g. `score desc` or `title_ssi asc`.
        schema:
          type: string
      responses:
        '200':
          description: Solr search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolrSearchResponse'
        '404':
          description: Unknown path under /dc.
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    DigitalObject:
      type: object
      description: Solr document for a digital object. Field names follow the Samvera/Hydra dynamic field suffix convention (_tesim text stored indexed multivalued, _ssi string stored indexed, _sim string indexed multivalued, _dtsi date stored indexed).
      properties:
        id:
          type: string
          description: ARK name segment, also the object's public identifier.
          example: bb38236995
        active_fedora_model_ssi:
          type: string
          description: Fedora model of the record.
          example: DamsObject
        object_state_ssi:
          type: string
          example: A
        title_tesim:
          type: array
          items:
            type: string
        date_tesim:
          type: array
          items:
            type: string
        unit_code_tesim:
          type: array
          items:
            type: string
        collection_name_tesim:
          type: array
          items:
            type: string
        resource_type_tesim:
          type: array
          items:
            type: string
        rightsHolder_tesim:
          type: array
          items:
            type: string
        otherRights_tesim:
          type: array
          description: Serialized rights/permission statements including basis and permission type.
          items:
            type: string
        discover_access_group_ssim:
          type: array
          description: Access groups permitted to discover the object; `public` for open material.
          items:
            type: string
        system_create_dtsi:
          type: string
          format: date-time
        system_modified_dtsi:
          type: string
          format: date-time
      additionalProperties: true
    SolrSearchResponse:
      type: object
      description: Raw Solr response envelope as returned by the Blacklight front end.
      properties:
        responseHeader:
          type: object
          properties:
            status:
              type: integer
              example: 0
            QTime:
              type: integer
              example: 15
            params:
              type: object
              additionalProperties: true
        response:
          type: object
          properties:
            numFound:
              type: integer
              example: 12939
            start:
              type: integer
            maxScore:
              type: number
            numFoundExact:
              type: boolean
            docs:
              type: array
              items:
                $ref: '#/components/schemas/DigitalObject'
        facet_counts:
          type: object
          description: Facet field counts. Observed facets include unit_sim, collection_sim, creator_sim, decade_sim, object_type_sim, subject_topic_sim, subject_cruise_sim, subject_lithology_sim, subject_common_name_sim, subject_scientific_name_sim, subject_anatomy_sim, subject_series_sim and subject_cultural_context_sim.
          additionalProperties: true
        highlighting:
          type: object
          additionalProperties: true