OpenAlex Pet

✅ Working Implementation: This pet uses a custom OpenAPI specification created from the official API documentation. All 21 auto-generated tools are fully functional. See Custom OpenAPI Spec for details.

Access scholarly research data from the OpenAlex API, including works, authors, institutions, sources (journals/repositories), topics, publishers, and funders.

Overview

OpenAlex is a free, open catalog of the world's scholarly research system. This pet provides access to:

• Works - Academic publications and their metadata
• Authors - Researcher profiles (searchable by ORCID)
• Institutions - Universities and research organizations (searchable by ROR)
• Journals - Academic journals and venues (searchable by ISSN)
• Concepts - Research topics and subject classifications

All tools are auto-generated from the OpenAlex OpenAPI specification.

Quick Start

1. Get an API Key

Visit openalex.org/settings/api to get a free API key.

• Free tier: 100,000 credits per day
• Single lookups: 1 credit per request
• List queries: 10 credits per page

2. Configure Environment

Create a .env file:

OPENALEX_API_KEY=your_api_key_here

# Optional: Add your email for "polite pool" access (better rate limits)
[email protected]

3. Test Connection

opencode run "test openalex connection" --print-logs

Available Tools

All 21 tools are auto-generated from a custom OpenAPI specification based on the current API:

Works (3 tools)

• openalex-get-work-by-id - Get work by OpenAlex ID (e.g., W2741809807)
• openalex-get-work-by-doi - Get work by DOI (e.g., 10.1371/journal.pone.0266781)
• openalex-list-works - Search and filter works with full-text search

Authors (3 tools)

• openalex-get-author-by-id - Get author by OpenAlex ID (e.g., A5023888391)
• openalex-get-author-by-orcid - Get author by ORCID (e.g., 0000-0003-1613-5981)
• openalex-list-authors - Search and filter authors

Sources (3 tools)

• openalex-get-source-by-id - Get source by OpenAlex ID (e.g., S137773608)
• openalex-get-source-by-issn - Get source by ISSN (e.g., 0028-0836)
• openalex-list-sources - Search and filter journals, repositories, conferences

Institutions (3 tools)

• openalex-get-institution-by-id - Get institution by OpenAlex ID (e.g., I136199984)
• openalex-get-institution-by-ror - Get institution by ROR (e.g., 02y3ad647)
• openalex-list-institutions - Search and filter institutions

Topics (2 tools)

• openalex-get-topic-by-id - Get topic by OpenAlex ID (e.g., T10178)
• openalex-list-topics - Search and filter research topics

Publishers (2 tools)

• openalex-get-publisher-by-id - Get publisher by OpenAlex ID (e.g., P4310319900)
• openalex-list-publishers - Search and filter publishers

Funders (2 tools)

• openalex-get-funder-by-id - Get funder by OpenAlex ID (e.g., F4320332161)
• openalex-list-funders - Search and filter funding agencies

Autocomplete (3 tools - requires env var)

Enable with OPENALEX_LOAD_AUTOCOMPLETE_TOOLS=true:

• openalex-autocomplete-works - Autocomplete works for search interfaces
• openalex-autocomplete-authors - Autocomplete authors
• openalex-autocomplete-institutions - Autocomplete institutions

Example Queries

# Test connection
opencode run "test openalex connection"

# Look up a work by DOI
opencode run "get work by DOI 10.1371/journal.pone.0266781"

# Look up an author by ORCID
opencode run "get author by ORCID 0000-0003-1613-5981"

# Search for works about machine learning
opencode run "search for recent works about machine learning"

# Look up an institution by ROR
opencode run "get institution by ROR 02y3ad647"

# Look up a journal by ISSN
opencode run "get source by ISSN 0028-0836"

# Find works from MIT
opencode run "search institutions for MIT then find recent works from them"

Identifier Types

OpenAlex uses several identifier systems:

| Type | Example | Description | |------|---------|-------------| | OpenAlex ID | A2741809807 | Internal OpenAlex identifier | | ORCID | 0000-0001-6187-6610 | Open Researcher and Contributor ID | | DOI | 10.1038/nature12373 | Digital Object Identifier | | ROR | 02y3ad647 | Research Organization Registry | | ISSN | 0028-0836 | International Standard Serial Number | | PMID | 23719680 | PubMed ID |

Rate Limits

The OpenAlex API has generous rate limits:

• Free tier: 100,000 credits/day
• Polite pool (with email): Higher priority and better performance
• Credits per operation:
  • Single entity lookup: 1 credit
  • List query (per page): 10 credits
  • Semantic search: 1,000 credits

Set OPENALEX_EMAIL to join the polite pool for better performance.

Regenerating Tools

When the OpenAlex API updates, regenerate the tools:

cd pets/openalex
pets generate-openapi --verbose

This will fetch the latest OpenAPI spec and regenerate openapi-client.ts.

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENALEX_API_KEY | Yes | API key from openalex.org/settings/api | | OPENALEX_EMAIL | No | Your email for polite pool access | | OPENALEX_HOST | No | Override base URL (default: https://api.openalex.org) |

OpenAPI Configuration

Defined in package.json:

{
  "openapiSpec": {
    "url": "https://raw.githubusercontent.com/ourresearch/openalex-api-docs/...",
    "baseUrl": "https://api.openalex.org",
    "authType": "apiKey",
    "apiKeyHeader": "X-API-Key",
    "authEnvVar": "OPENALEX_API_KEY"
  }
}

Resources

• OpenAlex Documentation
• OpenAlex API Guide for LLMs
• Get API Key
• OpenAPI Specification

Custom OpenAPI Specification

This pet uses a custom OpenAPI specification created from the official API documentation because OpenAlex's official spec is outdated (last updated Dec 2021).

What's Included

The custom spec (openapi-spec.yaml) includes:

✅ Current API Structure:

• Correct paths: /works/, /authors/, /sources/, /institutions/, /topics/, /publishers/, /funders/
• External ID lookups: /works/https://doi.org/{doi}, /authors/https://orcid.org/{orcid}, etc.
• Query parameters: search, filter, sort, per-page, page
• Autocomplete endpoints for building search interfaces

✅ All 7 Entity Types:

• Works (240M+ scholarly documents)
• Authors (researcher profiles)
• Sources (journals, repositories, conferences)
• Institutions (universities, research organizations)
• Topics (3-level subject hierarchy)
• Publishers (publishing organizations)
• Funders (funding agencies)

✅ Generated from Official Docs:

• Based on API Guide for LLMs
• Matches current API behavior (tested Feb 2026)
• Supports all common use cases

Why We Created This

OpenAlex's official OpenAPI spec:

• Last Updated: December 8, 2021 (3+ years ago)
• Problems: Uses outdated paths (/work/ vs /works/), missing entities (sources), wrong ID formats
• Status: Not hosted on API, appears unmaintained

Example of the problem:

# Official spec path (404 error)
curl "https://api.openalex.org/work/doi/10.1038/nature12373"

# Actual API (works)
curl "https://api.openalex.org/works/https://doi.org/10.1038/nature12373"

Our custom spec fixes all these issues and enables the full OpenAPI generation workflow.

Benefits of Custom Spec

1. Working Tools: All 21 generated tools work correctly with the current API
2. Comprehensive Coverage: All 7 entity types with get, list, and search operations
3. OpenPets Workflow: Demonstrates complete OpenAPI generation process
4. Maintainable: Easy to update when API changes
5. Documented: Includes descriptions, examples, and parameter details

Regenerating Tools

If the API changes, update the spec and regenerate:

cd pets/openalex
pets generate-openapi --verbose

The spec file is openapi-spec.yaml in this directory.

Contributing Back

We've documented the issues with the official spec in OPENAPI_ISSUES.md. If you'd like to help OpenAlex:

1. File an issue: https://github.com/ourresearch/openalex-docs/issues
2. Contact support: [email protected]
3. Share this working spec as a reference

Troubleshooting

"API key not set"

Make sure you've set OPENALEX_API_KEY in your .env file. Get a free key at openalex.org/settings/api.

Rate limit errors

If you're hitting rate limits:

1. Set OPENALEX_EMAIL to join the polite pool
2. Check your daily credit usage
3. Consider adding delays between requests

Invalid identifier format

Different lookups require different identifier formats:

• ORCID: Format 0000-0001-2345-6789 (with dashes)
• DOI: Full DOI like 10.1038/nature12373
• ROR: ROR ID like 02y3ad647
• ISSN: Format 0028-0836 or 2041-1723

Development

This pet uses the OpenAPI generation workflow:

1. OpenAPI spec → package.json openapiSpec configuration
2. Generate → pets generate-openapi creates openapi-client.ts
3. Import → index.ts imports and combines with test-connection tool

For more details, see docs/openapi-generation.md.