Semantic Scholar Pet

Access Semantic Scholar's Academic Graph API to search papers, authors, get citations, references, and recommendations for academic research.

Features

• Paper Search: Search for academic papers by keywords, title, or various identifiers (DOI, arXiv, PubMed, etc.)
• Author Search: Find authors and their publications
• Citation Analysis: Get citations and references for any paper
• Batch Operations: Retrieve multiple papers or authors at once
• Rich Metadata: Access titles, abstracts, authors, venues, citations, fields of study, and more

Quick Start

1. Install the Pet

cd pets/semantic-scholar
bun install

2. Configure (Optional)

The API works without an API key, but having one increases rate limits:

• Without API key: 100 requests per 5 minutes
• With API key: 1000 requests per 5 minutes

To get an API key:

1. Visit https://www.semanticscholar.org/product/api#api-key-form
2. Fill out the form and request an API key
3. Add it to your .env file:

cp .env.example .env
# Edit .env and add your API key
SEMANTIC_SCHOLAR_API_KEY=your_api_key_here

3. Test the Connection

bun run test:connection

Usage Examples

Search for Papers

opencode run "search for papers about transformer neural networks"
opencode run "find papers about BERT published after 2018"

Get Paper Details

opencode run "get details for paper with DOI 10.48550/arXiv.1706.03762"
opencode run "get the attention is all you need paper"

Citation Analysis

opencode run "find all citations for the transformer paper"
opencode run "get references for paper ID CorpusID:13756489"

Author Search

opencode run "search for author Geoffrey Hinton"
opencode run "get all papers by Yoshua Bengio"

Available Tools

This pet includes 15 tools: 14 auto-generated from the Semantic Scholar Graph API OpenAPI specification + 1 custom test-connection tool.

Note: The Recommendations and Datasets APIs are currently restricted/unavailable (return 404). Only the Graph API tools are functional.

Paper Tools

• semantic-scholar-get-graph-paper-relevance-search - Search papers by query
• semantic-scholar-get-graph-paper - Get paper details by ID
• semantic-scholar-get-graph-paper-citations - Get paper citations
• semantic-scholar-get-graph-paper-references - Get paper references
• semantic-scholar-get-graph-paper-authors - Get paper authors
• semantic-scholar-post-graph-get-papers - Batch retrieve papers
• semantic-scholar-get-graph-paper-autocomplete - Autocomplete paper titles
• semantic-scholar-get-graph-paper-bulk-search - Bulk paper search
• semantic-scholar-get-graph-paper-title-search - Search by exact title match

Author Tools

• semantic-scholar-get-graph-author-search - Search authors by name
• semantic-scholar-get-graph-author - Get author details
• semantic-scholar-get-graph-author-papers - Get author's papers
• semantic-scholar-post-graph-get-authors - Batch retrieve authors

Snippet Tools

• semantic-scholar-get-snippet-search - Search text snippets

Connection Tool

• semantic-scholar-test-connection - Test API connection and rate limits

Supported Paper Identifiers

The API supports multiple identifier types:

• DOI: 10.48550/arXiv.1706.03762
• arXiv ID: arXiv:1706.03762
• PubMed ID: PMID:29262144
• Corpus ID: CorpusID:13756489
• SHA hash: SHA-based identifiers
• URL: Direct Semantic Scholar URLs

Rate Limits

• Without API key: 100 requests per 5 minutes
• With API key: 1000 requests per 5 minutes

The test-connection tool shows your current rate limit status.

OpenAPI Generation

This pet was generated using the OpenAPI specification from Semantic Scholar Graph API:

# Regenerate Graph API tools
cd pets/semantic-scholar
bun run generate:graph

# Or regenerate all three APIs (includes restricted Recommendations and Datasets)
bun run generate:all

The configuration in package.json:

{
  "openapiSpec": {
    "url": "https://api.semanticscholar.org/graph/v1/swagger.json",
    "baseUrl": "https://api.semanticscholar.org/graph/v1",
    "authType": "apiKey",
    "apiKeyHeader": "x-api-key"
  },
  "openapiSpecs": [
    {
      "name": "graph",
      "url": "https://api.semanticscholar.org/graph/v1/swagger.json",
      "output": "openapi-client.ts"
    },
    {
      "name": "recommendations",
      "url": "https://api.semanticscholar.org/recommendations/v1/swagger.json",
      "output": "openapi-client-recommendations.ts"
    },
    {
      "name": "datasets",
      "url": "https://api.semanticscholar.org/datasets/v1/swagger.json",
      "output": "openapi-client-datasets.ts"
    }
  ]
}

Note: Only the Graph API is currently accessible. The Recommendations and Datasets APIs require special access or elevated API key permissions.

Development

Test the Pet

# Test connection
bun test:pet semantic-scholar --query "test connection"

# Search for papers
bun test:pet semantic-scholar --query "search for papers about GPT"

# Get paper details
bun test:pet semantic-scholar --query "get details for the attention is all you need paper"

Build and Validate

pets validate
pets build semantic-scholar

Testing Results

See TESTING.md for comprehensive test results including:

• API availability status
• Working vs restricted endpoints
• Rate limiting behavior
• OpenAPI generation workflow validation

Resources

• API Documentation: https://api.semanticscholar.org/api-docs/graph
• Get API Key: https://www.semanticscholar.org/product/api#api-key-form
• Semantic Scholar: https://www.semanticscholar.org/
• OpenPets Guide: ../../docs/openapi-generation.md

FAQ

Q: Do I need an API key? A: No, the API works without a key, but having one increases rate limits from 100 to 1000 requests per 5 minutes.

Q: How do I get an API key? A: Visit https://www.semanticscholar.org/product/api#api-key-form and fill out the request form.

Q: What paper identifiers are supported? A: DOI, arXiv ID, PubMed ID, Corpus ID, SHA hash, and direct URLs.

Q: Can I search for authors? A: Yes, use the author search tools to find authors and their publications.

Q: What data is available for papers? A: Title, abstract, authors, venue, year, citations, references, fields of study, influential citation count, and more.