openapi: 3.1.0
info:
  title: Art Institute of Chicago Public Agent Roles Artworks 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: Artworks
  description: Artworks from the Art Institute of Chicago collection (~120,000 records).
paths:
  /artworks:
    get:
      tags:
      - Artworks
      operationId: listArtworks
      summary: List Artworks
      description: A list of all artworks sorted by last updated date in descending order.
      parameters:
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Artwork'
                  info:
                    $ref: '#/components/schemas/Info'
                  config:
                    $ref: '#/components/schemas/Config'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /artworks/search:
    get:
      tags:
      - Artworks
      operationId: searchArtworks
      summary: Search Artworks
      description: Search artworks data in the aggregator. Artworks in the groups of essentials are boosted so they'll show up higher in results.
      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'
      - $ref: '#/components/parameters/Fields'
      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'
  /artworks/{id}:
    get:
      tags:
      - Artworks
      operationId: getArtwork
      summary: Get Artwork
      description: Retrieve a single artwork by ID.
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Artwork'
                  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
    ResourceId:
      name: id
      in: path
      description: Numeric resource identifier.
      required: true
      schema:
        type: integer
    Ids:
      name: ids
      in: query
      description: Comma-separated list of resource IDs to fetch in one call.
      required: false
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Number of records to return per page (default 12, max 100).
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 12
    Page:
      name: page
      in: query
      description: Page number (1-based).
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    SearchFacets:
      name: facets
      in: query
      description: Comma-separated list of fields to facet on for aggregations.
      required: false
      schema:
        type: string
    Fields:
      name: fields
      in: query
      description: Comma-separated list of fields to include in the response (sparse fieldsets).
      required: false
      schema:
        type: string
    SearchQ:
      name: q
      in: query
      description: Free-text search string.
      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
    Include:
      name: include
      in: query
      description: Comma-separated list of related resources to include (e.g. artist_pivots, dates, place_pivots, sites).
      required: false
      schema:
        type: string
    SearchQuery:
      name: query
      in: query
      description: Elasticsearch Query DSL JSON (URL-encoded).
      required: false
      schema:
        type: string
    SearchSort:
      name: sort
      in: query
      description: Sort specification (Elasticsearch sort syntax).
      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
    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
    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
    Artwork:
      type: object
      description: An artwork in the Art Institute of Chicago collection.
      properties:
        id:
          type: integer
          description: Unique numeric identifier.
        api_model:
          type: string
        api_link:
          type: string
          format: uri
        title:
          type: string
          description: Title of the artwork.
        alt_titles:
          type:
          - array
          - 'null'
          items:
            type: string
        thumbnail:
          type:
          - object
          - 'null'
        main_reference_number:
          type: string
          description: Accession number.
        has_not_been_viewed_much:
          type: boolean
        boost_rank:
          type:
          - integer
          - 'null'
        date_start:
          type:
          - integer
          - 'null'
        date_end:
          type:
          - integer
          - 'null'
        date_display:
          type:
          - string
          - 'null'
          description: Human-readable date string.
        date_qualifier_title:
          type:
          - string
          - 'null'
        date_qualifier_id:
          type:
          - integer
          - 'null'
        artist_display:
          type:
          - string
          - 'null'
          description: Human-readable artist credit line.
        place_of_origin:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
          description: Description (CC-BY 4.0).
        short_description:
          type:
          - string
          - 'null'
        dimensions:
          type:
          - string
          - 'null'
        dimensions_detail:
          type:
          - array
          - 'null'
          items:
            type: object
        medium_display:
          type:
          - string
          - 'null'
        inscriptions:
          type:
          - string
          - 'null'
        credit_line:
          type:
          - string
          - 'null'
        catalogue_display:
          type:
          - string
          - 'null'
        publication_history:
          type:
          - string
          - 'null'
        exhibition_history:
          type:
          - string
          - 'null'
        provenance_text:
          type:
          - string
          - 'null'
        edition:
          type:
          - string
          - 'null'
        publishing_verification_level:
          type: string
        internal_department_id:
          type:
          - integer
          - 'null'
        fiscal_year:
          type:
          - integer
          - 'null'
        fiscal_year_deaccession:
          type:
          - integer
          - 'null'
        is_public_domain:
          type: boolean
        is_zoomable:
          type: boolean
        max_zoom_window_size:
          type:
          - integer
          - 'null'
        copyright_notice:
          type:
          - string
          - 'null'
        has_multimedia_resources:
          type: boolean
        has_educational_resources:
          type: boolean
        has_advanced_imaging:
          type: boolean
        colorfulness:
          type:
          - number
          - 'null'
        color:
          type:
          - object
          - 'null'
        latitude:
          type:
          - number
          - 'null'
        longitude:
          type:
          - number
          - 'null'
        latlon:
          type:
          - string
          - 'null'
        is_on_view:
          type: boolean
        on_loan_display:
          type:
          - string
          - 'null'
        gallery_title:
          type:
          - string
          - 'null'
        gallery_id:
          type:
          - integer
          - 'null'
        nomisma_id:
          type:
          - string
          - 'null'
        artwork_type_title:
          type:
          - string
          - 'null'
        artwork_type_id:
          type:
          - integer
          - 'null'
        department_title:
          type:
          - string
          - 'null'
        department_id:
          type:
          - string
          - 'null'
        artist_id:
          type:
          - integer
          - 'null'
        artist_title:
          type:
          - string
          - 'null'
        alt_artist_ids:
          type: array
          items:
            type: integer
        artist_ids:
          type: array
          items:
            type: integer
        artist_titles:
          type: array
          items:
            type: string
        category_ids:
          type: array
          items:
            type: string
        category_titles:
          type: array
          items:
            type: string
        term_titles:
          type: array
          items:
            type: string
        style_id:
          type:
          - string
          - 'null'
        style_title:
          type:
          - string
          - 'null'
        alt_style_ids:
          type: array
          items:
            type: string
        style_ids:
          type: array
          items:
            type: string
        style_titles:
          type: array
          items:
            type: string
        classification_id:
          type:
          - string
          - 'null'
        classification_title:
          type:
          - string
          - 'null'
        alt_classification_ids:
          type: array
          items:
            type: string
        classification_ids:
          type: array
          items:
            type: string
        classification_titles:
          type: array
          items:
            type: string
        subject_id:
          type:
          - string
          - 'null'
        alt_subject_ids:
          type: array
          items:
            type: string
        subject_ids:
          type: array
          items:
            type: string
        subject_titles:
          type: array
          items:
            type: string
        material_id:
          type:
          - string
          - 'null'
        alt_material_ids:
          type: array
          items:
            type: string
        material_ids:
          type: array
          items:
            type: string
        material_titles:
          type: array
          items:
            type: string
        technique_id:
          type:
          - string
          - 'null'
        alt_technique_ids:
          type: array
          items:
            type: string
        technique_ids:
          type: array
          items:
            type: string
        technique_titles:
          type: array
          items:
            type: string
        theme_titles:
          type: array
          items:
            type: string
        image_id:
          type:
          - string
          - 'null'
          description: IIIF identifier; combine with config.iiif_url to retrieve images.
        alt_image_ids:
          type: array
          items:
            type: string
        document_ids:
          type: array
          items:
            type: string
        sound_ids:
          type: array
          items:
            type: string
        video_ids:
          type: array
          items:
            type: string
        text_ids:
          type: array
          items:
            type: string
        section_ids:
          type: array
          items:
            type: string
        section_titles:
          type: array
          items:
            type: string
        site_ids:
          type: array
          items:
            type: integer
        is_boosted:
          type: boolean
        suggest_autocomplete_all:
          type:
          - array
          - object
          - 'null'
        source_updated_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
      required:
      - id
      - title
      - api_model
      - api_link