{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAlex Scholarly Works Scraper — Search & Filter",
    "description": "Search OpenAlex scholarly works by topic, date, type, citations, author, institution, source, and open-access status. Returns one compact, traceable work record per dataset item for literature reviews and bibliometric research. API-backed metadata only; it does not download full text.",
    "version": "1.0",
    "x-build-id": "7Vc5kOnD1pIBU7rh9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/muhammadafzal~openalex-scholarly-works-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-muhammadafzal-openalex-scholarly-works-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/muhammadafzal~openalex-scholarly-works-scraper/runs": {
      "post": {
        "operationId": "runs-sync-muhammadafzal-openalex-scholarly-works-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/muhammadafzal~openalex-scholarly-works-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-muhammadafzal-openalex-scholarly-works-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "openAlexApiKey"
        ],
        "properties": {
          "openAlexApiKey": {
            "title": "OpenAlex API key",
            "type": "string",
            "description": "Your OpenAlex API key used to query the /works endpoint. Get a free key at https://openalex.org/settings/api and paste it here, for example 'oa_live_xxx'. This is a secret field and is not included in output records. It is not a DOI or an Apify API token."
          },
          "searchQuery": {
            "title": "Scholarly search query",
            "maxLength": 500,
            "type": "string",
            "description": "Free-text search across OpenAlex work titles, abstracts, and other indexed text. Enter a topic such as 'machine learning in healthcare'; it defaults to 'machine learning'. Set exactSearch=true for unstemmed matching. This is not a DOI lookup or a raw OpenAlex filter expression.",
            "default": "machine learning"
          },
          "exactSearch": {
            "title": "Use exact search",
            "type": "boolean",
            "description": "Use this to search without OpenAlex stemming, for example exactSearch=true with searchQuery='surgery'. It defaults to false for broader discovery. This only changes the search parameter and does not make the title an exact phrase match unless the query itself uses quotes.",
            "default": false
          },
          "advancedFilter": {
            "title": "Advanced OpenAlex filter",
            "maxLength": 1000,
            "type": "string",
            "description": "Optional OpenAlex filter expression appended to structured filters, for example 'type:article,has_abstract:true'. Use documented OpenAlex field names and comma-separated AND conditions. It defaults to empty. This is not a SQL WHERE clause and must not include api_key.",
            "default": ""
          },
          "publicationYearFrom": {
            "title": "Publication year from",
            "minimum": 1,
            "maximum": 2100,
            "type": "integer",
            "description": "Return works published in or after this year, for example 2020. Leave empty to disable the lower bound. Combine with publicationYearTo for a closed range. This is a publication-year filter, not a citation date."
          },
          "publicationYearTo": {
            "title": "Publication year to",
            "minimum": 1,
            "maximum": 2100,
            "type": "integer",
            "description": "Return works published in or before this year, for example 2024. Leave empty to disable the upper bound. It must be greater than or equal to publicationYearFrom. This is a publication-year filter, not a crawl cutoff."
          },
          "workTypes": {
            "title": "Work types",
            "type": "array",
            "description": "Limit results to OpenAlex work types such as article, book, dataset, dissertation, preprint, report, or review. Enter a list such as ['article','review']; values are combined as OR within the type filter. This is not a journal or subject category.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "openAccessOnly": {
            "title": "Open access only",
            "type": "boolean",
            "description": "Set true to keep only works OpenAlex marks as open access. It defaults to false. Open-access status is metadata and may not guarantee that a readable full-text file is available. This is not a license-rights determination.",
            "default": false
          },
          "minCitations": {
            "title": "Minimum citation count",
            "minimum": 0,
            "maximum": 1000000000,
            "type": "integer",
            "description": "Keep works with at least this OpenAlex cited_by_count, for example 50. Leave empty to include all citation counts. Counts reflect OpenAlex metadata and can change over time. This is not a quality or peer-review score."
          },
          "authorId": {
            "title": "OpenAlex author ID",
            "type": "string",
            "description": "Filter to works linked to one OpenAlex author, using 'A5023888391' or its full URL 'https://openalex.org/A5023888391'. Leave empty to disable. This is an OpenAlex ID, not an ORCID or author name search.",
            "default": ""
          },
          "institutionId": {
            "title": "OpenAlex institution ID",
            "type": "string",
            "description": "Filter to works associated with one OpenAlex institution, using 'I27837315' or its full URL. Leave empty to disable. This is an OpenAlex institution ID, not a free-text university name.",
            "default": ""
          },
          "sourceId": {
            "title": "OpenAlex source ID",
            "type": "string",
            "description": "Filter to works with a location associated with one OpenAlex source ID, such as 'S137773608'. Leave empty to disable. This is an OpenAlex source or journal ID, not an ISSN.",
            "default": ""
          },
          "countryCode": {
            "title": "Institution country code",
            "type": "string",
            "description": "Filter to works with an author institution in a two-letter country code such as 'us' or 'gb'. Leave empty to disable. Values are sent lowercase to OpenAlex. This is not the work language or publisher country.",
            "default": ""
          },
          "hasAbstract": {
            "title": "Require an indexed abstract",
            "type": "boolean",
            "description": "Set true to keep only works with an abstract indexed by OpenAlex; set false to require no abstract; leave empty to ignore abstract availability. It defaults to empty. This checks metadata availability, not full-text access."
          },
          "sort": {
            "title": "Result sort",
            "enum": [
              "relevance",
              "citedByCount",
              "-citedByCount",
              "publicationDate",
              "-publicationDate"
            ],
            "type": "string",
            "description": "Choose result ordering: relevance, citedByCount, or publicationDate; citations and publication date accept a leading '-' for descending order. It defaults to relevance for search and newest publication date for filter-only requests. This is not a custom sort expression.",
            "default": "relevance"
          },
          "maxResults": {
            "title": "Maximum works",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum number of schema-valid work records to store, from 1 to 1,000. It defaults to 25. The actor uses cursor pagination and stops at this cap; it does not download the entire OpenAlex catalog. This is a record cap, not an API page size.",
            "default": 25
          },
          "perPage": {
            "title": "OpenAlex results per page",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Number of works requested from OpenAlex per API page, from 1 to 100. It defaults to 100 for efficient cursor pagination. Smaller values can reduce response size. This is not the maximum number of output records.",
            "default": 100
          },
          "responseFormat": {
            "title": "Response format",
            "enum": [
              "concise",
              "detailed"
            ],
            "type": "string",
            "description": "Choose concise for smaller AI-agent records or detailed for abstracts and fuller author/institution context. It defaults to detailed. Both formats use the same stable field names and output schema. This does not change OpenAlex matching or citation counts.",
            "default": "detailed"
          },
          "contactEmail": {
            "title": "Contact email for OpenAlex polite pool",
            "type": "string",
            "description": "Optional email address sent as the OpenAlex mailto parameter to identify your requests. Enter a normal address such as 'research@example.org'. It defaults to empty. This is not an API key or a notification destination used by Apify.",
            "default": ""
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}