UCSF Industry Documents Library Solr API

openapi: 3.0.3
info:
  title: UCSF Industry Documents Library Solr API
  version: '5'
  description: >-
    Public, unauthenticated Apache Solr query interface over the UCSF Industry Documents
    Library (IDL) — an archive of 28.2 million internal documents from the tobacco, drug,
    chemical, food, fossil fuel and opioid industries, produced in litigation and preserved
    by the UCSF Library Center for Knowledge Management (CKM). The interface is documented
    by UCSF in "Industry Documents Data API v5" and is queried directly against the IDL
    Solr server. This OpenAPI description is DERIVED by API Evangelist from that UCSF
    documentation plus live probed responses; UCSF does not publish an OpenAPI document.
  termsOfService: https://www.industrydocuments.ucsf.edu/copyright/
  contact:
    name: UCSF Industry Documents Library
    url: https://www.industrydocuments.ucsf.edu/
  license:
    name: UCSF Copyright and Fair Use statement
    url: https://www.industrydocuments.ucsf.edu/copyright/
  x-operator: institution
  x-operator-evidence: >-
    servers[] host solr.idl.ucsf.edu is under the ucsf.edu registrable domain; idl.ucsf.edu
    redirects to www.industrydocuments.ucsf.edu; the CNAME target libckm.org is the UCSF
    Library Center for Knowledge Management's own infrastructure domain (github.com/ucsf-ckm,
    "UCSF Center for Knowledge Management", 74 repositories). No other institution in the
    248-university cohort claims this host.
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source:
      - https://www.industrydocuments.ucsf.edu/wp-content/uploads/2022/02/IndustryDocumentsDataAPI_v5.pdf
      - https://web.archive.org/web/20230130203403/https://industrydocuments.ucsf.edu/research-tools/api/
      - https://solr.idl.ucsf.edu/solr/ltdl3/query?q=id:kylw0221&wt=json
servers:
  - url: https://solr.idl.ucsf.edu/solr/ltdl3
    description: UCSF Industry Documents Library production Solr collection (ltdl3)
tags:
  - name: Documents
    description: Query the IDL document corpus by identifier or by Solr query syntax.
paths:
  /query:
    get:
      tags: [ Documents ]
      operationId: queryDocuments
      summary: Query the Industry Documents Library corpus
      description: >-
        Executes a Solr query against the IDL corpus. Retrieve a single document with
        `q=id:<8-character-id>`, or run a field query using Solr syntax with AND / OR / NOT
        and explicit parentheses. Results are paged 100 records at a time via `start`.
        Ampersands inside field values must be percent-encoded as %26.
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Solr query. Examples — `id:kylw0221`; `author:glantz`;
            `(author:glantz AND industry:tobacco)`;
            `((collection:"brown %26 williamson" AND type:letter) NOT brand:kool)`;
            `documentdateiso:[2001-01-01T00:00:00Z TO 2011-12-31T00:00:00Z]`.
          schema: { type: string }
          example: 'id:kylw0221'
        - name: wt
          in: query
          required: false
          description: Writer type — the response serialization format.
          schema:
            type: string
            default: xml
            enum: [ xml, json, python, ruby, php, csv ]
        - name: start
          in: query
          required: false
          description: >-
            Zero-based offset into the result set. Honoured. The deployed page size is 1000
            documents (UCSF's documentation says 100).
          schema: { type: integer, minimum: 0, default: 0 }
        - name: rows
          in: query
          required: false
          description: >-
            Accepted and echoed back in responseHeader.params, but NOT HONOURED by the deployed
            /query request handler as of 2026-08-19 — rows=0, rows=1, rows=5 and rows=100 all
            return the same 1000-document page. UCSF's own published documentation states that
            "we only return 100 records at a time" and instructs callers to page with start=100;
            the deployed page size is 1000. Page with `start` and read the actual length of
            response.docs rather than assuming a page size.
          schema: { type: integer, minimum: 0 }
          x-deployed-behavior: ignored
          x-verified: '2026-08-19'
        - name: fl
          in: query
          required: false
          description: Comma-separated list of fields to return.
          schema: { type: string }
      responses:
        '200':
          description: Solr response envelope containing matched documents.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SolrResponse' }
            application/xml:
              schema: { type: string }
            text/csv:
              schema: { type: string }
        '400':
          description: Malformed Solr query.
        '403':
          description: Request rejected — collection not exposed, or edge protection engaged.
        '404':
          description: Unknown Solr collection.
components:
  schemas:
    SolrResponse:
      type: object
      properties:
        responseHeader:
          type: object
          properties:
            status: { type: integer }
            QTime: { type: integer }
            params: { type: object, additionalProperties: true }
        response:
          type: object
          properties:
            numFound: { type: integer, description: Total records matching the query. }
            start: { type: integer }
            numFoundExact: { type: boolean }
            docs:
              type: array
              items: { $ref: '#/components/schemas/IndustryDocument' }
    IndustryDocument:
      type: object
      description: One archived industry document record as indexed in the ltdl3 collection.
      properties:
        id: { type: string, description: 'Eight-character document identifier: four letters then four digits. Case-insensitive.', example: kylw0221 }
        tid: { type: string, description: Legacy transfer identifier. }
        collection: { type: array, items: { type: string } }
        collectioncode: { type: array, items: { type: string } }
        industry: { type: array, items: { type: string }, description: 'tobacco | drug | chemical | food | fossilfuel | opioids' }
        availability: { type: array, items: { type: string }, description: 'e.g. public, no restrictions' }
        case: { type: array, items: { type: string }, description: Litigation case the document was produced in. }
        title: { type: string }
        author: { type: array, items: { type: string } }
        mentioned: { type: array, items: { type: string } }
        witness: { type: string }
        type: { type: array, items: { type: string } }
        brand: { type: array, items: { type: string } }
        box: { type: string }
        pages: { type: integer }
        bates: { type: string }
        batesexpanded: { type: string, description: Expanded bates range — query bates numbers against this field. }
        description: { type: string }
        documentdate: { type: string, description: 'String date in "YYYY Month DD" form, e.g. "2014 November 25".' }
        documentdateiso: { type: string, format: date-time, description: ISO form of documentdate — use this field for range queries. }
        dateaddeducsf: { type: string }
        dateaddedindustry: { type: string }
        datemodifiedindustry: { type: string }
        dateshipped: { type: string }
        minnesotarequestnumber: { type: string }
        cited: { type: array, items: { type: string } }