UBC Library Open Collections API

openapi: 3.0.3
info:
  title: UBC Library Open Collections API
  description: >-
    REST/JSON API over UBC Library Open Collections — the University of British Columbia's
    digitized historical, archival and research collections. The service is operated by UBC
    Library on UBC's own infrastructure at oc-index.library.ubc.ca; the search resource is
    backed by an ElasticSearch index and is versioned by the ElasticSearch syntax it accepts
    (currently 8.5).

    PROVENANCE: this description is DERIVED. UBC Library does not publish an OpenAPI
    description of this API. It was reconstructed from UBC Library's own documentation source
    (https://github.com/ubc-library/docs-open-collections-api, data/api.twig.html and
    data/reference.twig.html) and confirmed against live responses from
    https://oc-index.library.ubc.ca on 2026-08-19. Only routes that returned a real,
    non-"Missed Route" payload are described here.

    OPERATOR: institution. Host oc-index.library.ubc.ca is under ubc.ca, UBC's own
    registrable domain, and the software is UBC Library's own (see the ubc-library GitHub
    organization). This is not a vendor platform running under UBC's name.
  version: '1'
  contact:
    name: UBC Library Open Collections
    url: https://open.library.ubc.ca/docs
  termsOfService: https://www.ubc.ca/site/legal.html
  license:
    name: UBC Terms of Use
    url: https://www.ubc.ca/site/legal.html
servers:
- url: https://oc-index.library.ubc.ca
  description: UBC Library Open Collections production index (verified live 2026-08-19).
externalDocs:
  description: UBC Library Open Collections API documentation
  url: https://open.library.ubc.ca/docs
security:
- apiKeyQuery: []
- {}
tags:
- name: Collections
  description: Collection-level metadata and item traversal.
- name: Search
  description: ElasticSearch-backed search across all indexed Open Collections items.
paths:
  /collections:
    get:
      operationId: listCollections
      summary: List all collections
      description: >-
        Returns every collection indexed in Open Collections as a map of collection ordinal to
        internal collection identifier. Verified live 2026-08-19; returned 362 entries.
      tags:
      - Collections
      responses:
        '200':
          description: Envelope whose data member maps collection ordinals to collection identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionListEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/{name}:
    get:
      operationId: getCollection
      summary: Get collection metadata
      description: >-
        Returns descriptive metadata for a single collection addressed by its Open Collections
        nickname (for example `berkpost`). Verified live 2026-08-19.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionName'
      responses:
        '200':
          description: Collection metadata envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDetailEnvelope'
        '400':
          description: >-
            Collection not found. The service returns HTTP 400 with `api_text` set to
            "Collection '<name>' not found" rather than a 404. Verified live 2026-08-19.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/{name}/items:
    get:
      operationId: listCollectionItems
      summary: List the items in a collection
      description: >-
        Traverses every item in a collection. UBC Library documents `limit` and `offset` for
        large collections to avoid slow responses.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionName'
      - name: limit
        in: query
        description: Maximum number of items to return.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        description: Zero-based offset of the first item to return.
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Item list envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '400':
          description: Collection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/{name}/items/{itemId}:
    get:
      operationId: getCollectionItem
      summary: Get a single item's metadata
      description: >-
        Returns the full descriptive metadata for one digitized item. Each field carries its
        label, value, the IRI of the property it maps to (Dublin Core Terms, EDM, DPLA) and a
        human explanation of that property.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionName'
      - name: itemId
        in: path
        description: Open Collections item identifier, for example `1.0000153`.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Item metadata envelope with IRI-annotated fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemDetailEnvelope'
        '400':
          description: Collection or item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
  /search/8.5:
    get:
      operationId: search
      summary: Search all indexed items
      description: >-
        ElasticSearch-backed search across every indexed Open Collections item. The `8.5`
        path segment is the ElasticSearch query syntax version the endpoint accepts, not a
        product version of the API. Verified live 2026-08-19 with `?q=salmon`.

        NOTE: the trailing-slash form `/search/8.5/` does NOT route — it returns HTTP 200 with
        `"route": "Missed Route"`. The catalog previously recorded the trailing-slash form as a
        working endpoint; it is not.
      tags:
      - Search
      parameters:
      - name: q
        in: query
        description: ElasticSearch query string.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ElasticSearch response envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: >-
        Open Collections reads are available without a key at the shared public rate of 10
        requests per minute per IP. UBC Library issues a per-user key on email registration
        which raises the ceiling to 200 requests per minute. Registration is at
        https://open.library.ubc.ca/docs.
  parameters:
    CollectionName:
      name: name
      in: path
      description: Open Collections nickname of the collection, for example `berkpost`.
      required: true
      schema:
        type: string
  responses:
    RateLimited:
      description: >-
        Rate limit exceeded. Returned with HTTP 429 and an `api_text` message naming the
        client IP, the ceiling and the seconds until it expires. Verified live 2026-08-19.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    Envelope:
      type: object
      description: Common response envelope returned by every Open Collections endpoint.
      properties:
        http_code:
          type: integer
          description: Status code repeated inside the body.
        endpoint:
          type: string
          description: Method and path the service resolved the request to.
        api_code:
          type: integer
          description: Internal Open Collections response code.
        api_text:
          type: string
          description: Human-readable result or error text, also carrying the API version.
        user_ip:
          type: string
          description: Client IP as seen by the service; used in rate-limit messages.
        data:
          description: Endpoint-specific payload, or null on error.
          nullable: true
      required:
      - http_code
      - endpoint
      - api_code
      - api_text
    ErrorEnvelope:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        description: Envelope where data is null and api_text carries the reason.
        properties:
          data:
            nullable: true
            type: object
    CollectionListEnvelope:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
            description: Map of collection ordinal to internal collection identifier.
            additionalProperties:
              type: integer
    CollectionDetailEnvelope:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Collection'
    Collection:
      type: object
      properties:
        items:
          type: integer
          description: Number of items in the collection.
        title:
          type: string
          description: Display title of the collection.
        description:
          type: string
          description: HTML description of the collection.
    ItemDetailEnvelope:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
            description: >-
              Map of metadata group name (Collection, Creator, Title, ...) to the list of
              annotated field values in that group.
            additionalProperties:
              type: array
              items:
                $ref: '#/components/schemas/MetadataField'
    MetadataField:
      type: object
      description: One IRI-annotated metadata value.
      properties:
        label:
          type: string
        value:
          type: string
        iri:
          type: string
          format: uri
          description: IRI of the property this value maps to.
        explain:
          type: string
          description: Human explanation of the property.
        attrs:
          type: object
          properties:
            lang:
              type: string
            ns:
              type: string
              format: uri
            classmap:
              type: string
            property:
              type: string
    SearchEnvelope:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/SearchResult'
    SearchResult:
      type: object
      description: ElasticSearch response body passed through by Open Collections.
      properties:
        took:
          type: integer
        timed_out:
          type: boolean
        _shards:
          type: object
          properties:
            total:
              type: integer
            successful:
              type: integer
            skipped:
              type: integer
            failed:
              type: integer
        hits:
          type: object
          properties:
            total:
              type: integer
            max_score:
              type: number
            hits:
              type: array
              items:
                $ref: '#/components/schemas/SearchHit'
    SearchHit:
      type: object
      properties:
        _index:
          type: string
        _id:
          type: string
        _score:
          type: number
        _source:
          type: object
          description: Indexed Dublin-Core-aligned item metadata.
x-operator: institution
x-operator-note: >-
  Host oc-index.library.ubc.ca is under ubc.ca and the software is UBC Library's own. No vendor
  platform is involved. This OpenAPI description is DERIVED by API Evangelist from UBC Library's
  documentation source and live probes; UBC publishes no OpenAPI for it.