openapi: 3.1.0
info:
  title: Art Institute of Chicago Public Agent Roles Search API
  description: 'The Art Institute of Chicago publishes an open, REST + Elasticsearch-style API for ~120,000 artworks plus artists/agents, places, galleries, exhibitions, tours, mobile sounds, products, publications, sections, sites, educational resources, digital and printed publications, and static archive images. Most data is CC0 1.0; descriptions and places are CC-BY 4.0. No API key required. Anonymous limit: 60 requests/minute per IP. Clients should send an AIC-User-Agent header (recommended for courtesy tracking).'
  termsOfService: https://www.artic.edu/terms/terms-and-conditions
  contact:
    email: engineering@artic.edu
    url: https://api.artic.edu/docs/
  license:
    name: CC0 1.0 (data) / CC-BY 4.0 (descriptions and place data)
    url: https://creativecommons.org/publicdomain/zero/1.0/
  version: '1.14'
servers:
- url: https://api.artic.edu/api/v1
  description: Public API v1
tags:
- name: Search
  description: Cross-resource Elasticsearch-style search.
paths:
  /search:
    get:
      tags:
      - Search
      operationId: searchAll
      summary: Search All Resources
      description: Full-text and Elasticsearch DSL search across all indexed resources.
      parameters:
      - $ref: '#/components/parameters/SearchQ'
      - $ref: '#/components/parameters/SearchQuery'
      - $ref: '#/components/parameters/SearchSort'
      - $ref: '#/components/parameters/SearchFrom'
      - $ref: '#/components/parameters/SearchSize'
      - $ref: '#/components/parameters/SearchFacets'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  preference:
                    type:
                    - string
                    - 'null'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchHit'
                  info:
                    $ref: '#/components/schemas/Info'
                  config:
                    $ref: '#/components/schemas/Config'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    SearchFrom:
      name: from
      in: query
      description: Elasticsearch offset pagination starting record.
      required: false
      schema:
        type: integer
        minimum: 0
    SearchQuery:
      name: query
      in: query
      description: Elasticsearch Query DSL JSON (URL-encoded).
      required: false
      schema:
        type: string
    SearchSize:
      name: size
      in: query
      description: Elasticsearch page size (max 100).
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
    SearchSort:
      name: sort
      in: query
      description: Sort specification (Elasticsearch sort syntax).
      required: false
      schema:
        type: string
    SearchFacets:
      name: facets
      in: query
      description: Comma-separated list of fields to facet on for aggregations.
      required: false
      schema:
        type: string
    SearchQ:
      name: q
      in: query
      description: Free-text search string.
      required: false
      schema:
        type: string
  schemas:
    SearchHit:
      type: object
      description: A single search hit (Elasticsearch _source projected fields).
      properties:
        _score:
          type: number
        id:
          type: integer
        api_model:
          type: string
        api_link:
          type: string
          format: uri
        title:
          type: string
        timestamp:
          type: string
          format: date-time
    Info:
      type: object
      properties:
        license_text:
          type: string
        license_links:
          type: array
          items:
            type: string
            format: uri
        version:
          type: string
    Pagination:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        total_pages:
          type: integer
        current_page:
          type: integer
        next_url:
          type: string
          format: uri
    Error:
      type: object
      properties:
        status:
          type: integer
        error:
          type: string
        detail:
          type: string
    Config:
      type: object
      properties:
        iiif_url:
          type: string
          format: uri
        website_url:
          type: string
          format: uri