2. Authentication & Common¶

2.1 API Key¶

The API can be used without an API key, but rate limits apply. Using an API key provides higher throughput.

x-api-key: YOUR_API_KEY

Note: The header name x-api-key is case-sensitive.

2.2 Common Request Format¶

• Content-Type: application/json
• Accept: application/json
• All special characters must be URL-encoded

2.3 fields Parameter¶

A core parameter used across nearly all endpoints. Specify a comma-separated list of fields to control response size.

?fields=title,authors,year,citationCount

Default behavior: - When fields is omitted → papers: only paperId + title, authors: only authorId + name - fields is a single-value string parameter (not multi-value)

Nested fields (subfields):

Use dot notation (.) to specify subfields:

Examples:

fields=title,url                                    # basic fields only
fields=title,embedding.specter_v2                   # SPECTER v2 embedding
fields=title,authors,citations.title,citations.abstract  # authors + citation title/abstract
fields=url,papers.year,papers.authors               # paper subfields in author API

Note: For /snippet/search, fields use the form snippet.text, snippet.snippetKind. paper and score are always returned and cannot be specified.

2.4 Pagination¶

Two pagination methods exist:

Offset-based example:

GET /paper/search?query=LLM&offset=0&limit=10
GET /paper/search?query=LLM&offset=10&limit=10

Token-based example:

GET /paper/search/bulk?query=LLM
→ Response includes "token": "abc123"
GET /paper/search/bulk?query=LLM&token=abc123

2.5 Paper ID Formats¶

Various external IDs can be used to specify papers:

Supported URL sites: semanticscholar.org, arxiv.org, aclweb.org, acm.org, biorxiv.org

2.6 Common Filter Parameters¶

Filters shared across search endpoints (/paper/search, /paper/search/bulk, /paper/search/match, /snippet/search):

publicationDateOrYear¶

Date range format: <start>:<end> (each in YYYY-MM-DD format, both sides optional)

Papers with unknown exact publication dates are treated as January 1^st of that year. Even when publicationDate is null, year is always present.

year¶

Simple year-based filter:

publicationTypes¶

Publication type filter (comma-separated, OR logic):

Example: publicationTypes=Review,JournalArticle → papers that are Review or JournalArticle

fieldsOfStudy¶

Field of study filter (comma-separated, OR logic):

Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, Linguistics

Example: fieldsOfStudy=Physics,Mathematics → papers in Physics or Mathematics

venue¶

Venue filter (comma-separated). Both full names and ISO4 abbreviations are accepted:

Example: venue=Nature,Radiology or venue=N. Engl. J. Med.

openAccessPdf¶

Filter for papers with open access PDF. Include the parameter without a value:

?query=LLM&openAccessPdf

minCitationCount¶

Minimum citation count filter:

?query=LLM&minCitationCount=200

2.7 Response Size Limit¶

• Maximum single response size for all endpoints: 10MB
• On exceeding: 400 error "Response would exceed maximum size..."
• Resolution: reduce limit, minimize fields, split batches

2.8 Error Responses¶