{"openapi":"3.1.0","info":{"title":"Open Alex Reference Data (BYOK) API","version":"0.1.0","description":"Open Alex Reference Data (BYOK) lets an AI assistant read your own Open Alex Reference Data data through the Open Alex Reference Data API with a key you supply (OpenAlex API key). Read-only: 12 tools (search_publishers, get_publisher, search_awards, get_award, list_countries, get_country, list_languages, list_licenses, list_domains, list_fields, list_subfields, search_keywords). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-openalex-reference.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-openalex-reference/docs"},"termsOfService":"https://connectorbay.com/byok-openalex-reference/terms"},"servers":[{"url":"https://byok-openalex-reference.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-openalex-reference/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_publishers":{"post":{"operationId":"search_publishers","summary":"Search scholarly publishers with their parent/imprint hierarchy, countries, homepage and counts of works and citations. ","description":"Search scholarly publishers with their parent/imprint hierarchy, countries, homepage and counts of works and citations. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Which publishers in the Netherlands have the most works\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filters field:value that are ANDed, for example country_codes:NL. Filters on any publisher field, for example hierarchy_level:0 or lineage:P4310319965.","title":"Filter"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example works_count:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"search_publishersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_publisher":{"post":{"operationId":"get_publisher","summary":"Get one publisher by OpenAlex id: hierarchy, countries, homepage, external ids (ROR, Wikidata) and counts. List calls co","description":"Get one publisher by OpenAlex id: hierarchy, countries, homepage, external ids (ROR, Wikidata) and counts. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Show the OpenAlex record of publisher P4310319965\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publisher_id":{"description":"OpenAlex publisher id, for example 'P4310319965'.","maxLength":30,"title":"Publisher Id","type":"string"}},"required":["publisher_id"],"title":"get_publisherArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_awards":{"post":{"operationId":"search_awards","summary":"Search research grants and awards with funder, funder award number, funding type, amount, years and number of funded wor","description":"Search research grants and awards with funder, funder award number, funding type, amount, years and number of funded works (no investigator names). List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Find research awards about CRISPR funded by the NIH\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filters field:value that are ANDed, for example funder.id:F4320332161,start_year:2020. Filters such as funder.id, start_year, end_year, funding_type or provenance.","title":"Filter"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example amount:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"search_awardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_award":{"post":{"operationId":"get_award","summary":"Get one research award by OpenAlex id: title, funder, award number, amount, years and provenance. List calls cost a smal","description":"Get one research award by OpenAlex id: title, funder, award number, amount, years and provenance. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Show the OpenAlex award G5066037109\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"award_id":{"description":"OpenAlex award id, for example 'G5066037109'.","maxLength":30,"title":"Award Id","type":"string"}},"required":["award_id"],"title":"get_awardArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_countries":{"post":{"operationId":"list_countries","summary":"List countries with ISO 3166-1 alpha-2 and alpha-3 codes, continent, Global South flag, Wikidata id and counts of works.","description":"List countries with ISO 3166-1 alpha-2 and alpha-3 codes, continent, Global South flag, Wikidata id and counts of works. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Give me the ISO codes and continent of the countries in OpenAlex\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filters field:value that are ANDed, for example is_global_south:true. Filters on country fields such as is_global_south or continent.id.","title":"Filter"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example works_count:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_countriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_country":{"post":{"operationId":"get_country","summary":"Get one country by ISO 3166-1 alpha-2 code: names, alpha-3 code, continent, ids and counts. List calls cost a small amou","description":"Get one country by ISO 3166-1 alpha-2 code: names, alpha-3 code, continent, ids and counts. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Show the OpenAlex record of country DE\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"description":"ISO 3166-1 alpha-2 country code, for example 'US'.","maxLength":2,"title":"Country Code","type":"string"}},"required":["country_code"],"title":"get_countryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_languages":{"post":{"operationId":"list_languages","summary":"List the languages work metadata can be in, with ISO 639-1 code in the id and counts of works. List calls cost a small a","description":"List the languages work metadata can be in, with ISO 639-1 code in the id and counts of works. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Which languages have the most works in OpenAlex\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example works_count:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_languagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_licenses":{"post":{"operationId":"list_licenses","summary":"List the open-access licenses a work location can carry, with name, URL, description and counts of works. List calls cos","description":"List the open-access licenses a work location can carry, with name, URL, description and counts of works. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Which open access licenses does OpenAlex distinguish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example works_count:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_licensesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_domains":{"post":{"operationId":"list_domains","summary":"List the four top-level domains of the OpenAlex subject classification, with their fields and counts. List calls cost a ","description":"List the four top-level domains of the OpenAlex subject classification, with their fields and counts. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"What are the top-level subject domains in OpenAlex\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_domainsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_fields":{"post":{"operationId":"list_fields","summary":"List the 26 fields of the OpenAlex subject classification, each with its domain and subfields. List calls cost a small a","description":"List the 26 fields of the OpenAlex subject classification, each with its domain and subfields. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"List the fields under the Health Sciences domain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filters field:value that are ANDed, for example domain.id:4. Filters on field attributes such as domain.id.","title":"Filter"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_fieldsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_subfields":{"post":{"operationId":"list_subfields","summary":"List subfields of the OpenAlex subject classification with their parent field and domain. List calls cost a small amount","description":"List subfields of the OpenAlex subject classification with their parent field and domain. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Find the subfields of the field Medicine\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filters field:value that are ANDed, for example field.id:27. Filters on subfield attributes such as field.id or domain.id.","title":"Filter"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"list_subfieldsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_keywords":{"post":{"operationId":"search_keywords","summary":"Search the OpenAlex keyword vocabulary (short topic-derived phrases) with counts of tagged works. List calls cost a smal","description":"Search the OpenAlex keyword vocabulary (short topic-derived phrases) with counts of tagged works. List calls cost a small amount of the key's daily budget (free keys have about one US dollar per day); lookups of a single record are cheaper. Use for \"Find OpenAlex keywords related to remote sensing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against names.","title":"Search"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, prefix with - for descending, for example works_count:desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number for basic paging (up to 10,000 results in total).","title":"Page"}},"title":"search_keywordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}