openapi: 3.0.3
info:
  title: Europeana and Record Search API
  description: The Europeana REST API gives programmatic access to over 50 million cultural heritage items, including books, paintings, films, museum objects, and archival records aggregated from more than 3,500 institutions across Europe. The Search API discovers records, and the Record API returns the full metadata for a specific item.
  version: '2.0'
  contact:
    name: Europeana Pro
    url: https://pro.europeana.eu/page/apis
  license:
    name: EUPL 1.2
    url: https://eupl.eu/1.2/en/
  termsOfService: https://www.europeana.eu/en/rights
servers:
- url: https://api.europeana.eu/record/v2
  description: Europeana Record/Search v2 API
security:
- apiKeyAuth: []
tags:
- name: Search
  description: Discover records via keyword, faceted, and filtered search
paths:
  /search.json:
    get:
      summary: Search records
      description: Search the Europeana collection using keyword, facet, and filter parameters.
      operationId: searchRecords
      tags:
      - Search
      parameters:
      - name: query
        in: query
        required: true
        description: Search query string.
        schema:
          type: string
          example: mona lisa
      - name: qf
        in: query
        required: false
        description: Query refinement filter (repeatable).
        schema:
          type: array
          items:
            type: string
      - name: rows
        in: query
        required: false
        description: Number of records to return (max 100).
        schema:
          type: integer
          default: 12
      - name: start
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: profile
        in: query
        required: false
        description: Response profile (minimal, standard, rich, facets).
        schema:
          type: string
          enum:
          - minimal
          - standard
          - rich
          - facets
          - portal
      - name: media
        in: query
        required: false
        schema:
          type: boolean
      - name: thumbnail
        in: query
        required: false
        schema:
          type: boolean
      - name: reusability
        in: query
        required: false
        schema:
          type: string
          enum:
          - open
          - restricted
          - permission
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Missing or invalid API key
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        success:
          type: boolean
        itemsCount:
          type: integer
        totalResults:
          type: integer
        items:
          type: array
          items:
            type: object
        facets:
          type: array
          items:
            type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: wskey
      description: Europeana API key. Register at https://pro.europeana.eu/pages/get-api.