openapi.yaml

openapi: 3.1.0
info:
  title: OpenAlex API
  description: An OpenAPI specification for the OpenAlex API
  version: 1.0.0
  license:
    name: CC0 1.0 Universal
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
  - url: https://api.openalex.org

security:
  - PoliteEmail: []

components:
  securitySchemes:
    PoliteEmail:
      type: apiKey
      name: email
      in: header
      description: Optional email address for polite requests
  schemas:
    Autocomplete:
      $ref: './components/schemas/autocomplete.yaml'

  parameters:
    filter:
      $ref: './components/parameters/filter_parameter.yaml'
    search:
      $ref: './components/parameters/search_parameter.yaml'
    sort:
      $ref: './components/parameters/sort_parameter.yaml'
    page:
      $ref: './components/parameters/page_parameter.yaml'
    per_page:
      $ref: './components/parameters/per_page_parameter.yaml'
    select:
      $ref: './components/parameters/select_parameter.yaml'
    group_by:
      $ref: './components/parameters/group_by_parameter.yaml'
    autocomplete:
      $ref: './components/parameters/autocomplete_parameter.yaml'
    cursor:
      $ref: './components/parameters/cursor_page_parameter.yaml'



paths:
  /authors:
    $ref: './paths/authors.yaml'
  /concepts:
    $ref: './paths/concepts.yaml'
  /funders:
    $ref: './paths/funders.yaml'
  /institutions:
    $ref: './paths/institutions.yaml'
  /keywords:
    $ref: './paths/keywords.yaml'
  /publishers:
    $ref: './paths/publishers.yaml'
  /sources:
    $ref: './paths/sources.yaml'
  /topics:
    $ref: './paths/topics.yaml'
  /works:
    $ref: './paths/works.yaml'
  /autocomplete/{entity_type}:
    get:
      operationId: autocompleteEntities
      summary: Autocomplete entities
      description: Returns a list of entities that match the given query string for autocomplete suggestions.
      parameters:
        - name: entity_type
          in: path
          required: true
          schema:
            type: string
            enum: [authors, concepts, funders, institutions, publishers, sources, topics, works]
        - $ref: '#/components/parameters/autocomplete'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Autocomplete'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message describing the bad request