openapi: 3.0.3
info:
  title: Smithsonian Open Access Content Search API
  description: The Smithsonian Open Access API provides programmatic access to the Smithsonian Institution's publicly available collection data. Search and retrieve objects, artworks, natural history specimens, and related media from 19 museums, 21 libraries, and 9 research centers. Requires an API key from api.data.gov.
  version: 1.0.0
  contact:
    name: Smithsonian Open Access
    url: https://www.si.edu/openaccess/devtools
    email: openaccess@si.edu
  license:
    name: Creative Commons Zero (CC0)
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://edan.si.edu/openaccess
  description: Smithsonian EDAN Open Access API
security:
- ApiKey: []
tags:
- name: Search
paths:
  /api/search/search:
    get:
      operationId: searchContent
      summary: Search Collections
      description: Full-text search across Smithsonian collections. Supports filtering by content type, row grouping, and sorting. Returns paginated results with metadata about matching collection items.
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: true
        description: Search query string
        schema:
          type: string
      - name: start
        in: query
        required: false
        description: Zero-based offset for pagination
        schema:
          type: integer
          default: 0
      - name: rows
        in: query
        required: false
        description: Number of results to return
        schema:
          type: integer
          default: 10
          maximum: 100
      - name: sort
        in: query
        required: false
        description: Sort order for results
        schema:
          type: string
          enum:
          - relevancy
          - id
          - newest
          - updated
          - random
          default: relevancy
      - name: type
        in: query
        required: false
        description: Filter by EDAN schema/record type
        schema:
          type: string
          enum:
          - edanmdm
          - ead_collection
          - ead_component
          - all
          default: all
      - name: row_group
        in: query
        required: false
        description: Group results by object type
        schema:
          type: string
          enum:
          - objects
          - archives
      - name: api_key
        in: query
        required: true
        description: API key obtained from api.data.gov
        schema:
          type: string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request - missing or invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
  /api/search/category_search:
    get:
      operationId: searchByCategory
      summary: Search by Category
      description: Search Smithsonian collections filtered by a subject category. Categories include art and design, history and culture, and science and technology.
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: true
        description: Search query string
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: Subject category filter
        schema:
          type: string
          enum:
          - art_design
          - history_culture
          - science_technology
      - name: start
        in: query
        required: false
        description: Zero-based offset for pagination
        schema:
          type: integer
          default: 0
      - name: rows
        in: query
        required: false
        description: Number of results to return
        schema:
          type: integer
          default: 10
      - name: sort
        in: query
        required: false
        description: Sort order
        schema:
          type: string
          enum:
          - relevancy
          - id
          - newest
          - updated
          - random
      - name: api_key
        in: query
        required: true
        description: API key obtained from api.data.gov
        schema:
          type: string
      responses:
        '200':
          description: Category search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /api/search/terms:
    get:
      operationId: searchTerms
      summary: Get Search Terms
      description: Retrieves available search terms and facet values for a specified category. Useful for building search filters and faceted navigation. Optionally filter terms by starting character.
      tags:
      - Search
      parameters:
      - name: category
        in: query
        required: true
        description: The facet category to retrieve terms for
        schema:
          type: string
          enum:
          - culture
          - data_source
          - date
          - object_type
          - online_media_type
          - place
          - topic
          - unit_code
      - name: starts_with
        in: query
        required: false
        description: Filter terms that start with this character or string
        schema:
          type: string
      - name: api_key
        in: query
        required: true
        description: API key obtained from api.data.gov
        schema:
          type: string
      responses:
        '200':
          description: Available search terms for the category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermsResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
components:
  schemas:
    TermsResult:
      type: object
      description: Available search terms for a category
      properties:
        status:
          type: integer
        response:
          type: object
          properties:
            terms:
              type: array
              items:
                type: object
                properties:
                  term:
                    type: string
                  count:
                    type: integer
    SearchResult:
      type: object
      description: Paginated search results from the Smithsonian collections
      properties:
        status:
          type: integer
          description: HTTP status code
        responseCode:
          type: integer
        message:
          type: string
        response:
          type: object
          properties:
            rows:
              type: array
              items:
                $ref: '#/components/schemas/SearchItem'
            rowCount:
              type: integer
              description: Total number of matching results
            start:
              type: integer
              description: Offset of first result
            rows_returned:
              type: integer
              description: Number of results returned
            facets:
              type: array
              items:
                $ref: '#/components/schemas/Facet'
    Facet:
      type: object
      description: A search facet with counts
      properties:
        fieldName:
          type: string
        label:
          type: string
        values:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              count:
                type: integer
    SearchItem:
      type: object
      description: A search result item (summary view)
      properties:
        id:
          type: string
        title:
          type: string
        unitCode:
          type: string
        type:
          type: string
        url:
          type: string
          format: uri
        thumbnail:
          type: string
          format: uri
          description: URL to thumbnail image if available
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: API key obtained by registering at api.data.gov