Research and reading · OpenAlex

academic.search

Searches OpenAlex works. Each result carries year, venue, authors, citation count and DOI; details adds the abstract, referenced-works count and an open-access PDF when one exists.

Operation: POST /v1/capabilities/academic.search/execute
operationId: executeAcademicSearch
Typical credits: 0
Search deadline: 15 s server-side
Paging: page
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: Free (OpenAlex polite pool). Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/academic.search/execute, JSON, validated against the AcademicSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of academic.search
Field	Type	Required	Default	Constraints and description
query	string	yes		min length 1, max length 500
from_year	integer	no		min 1000, max 2100
to_year	integer	no		min 1000, max 2100
open_access_only	boolean	no	false
sort	"relevance" \| "cited" \| "recent"	no	"relevance"
num	integer	no	10	min 1, max 25 Results per page (1-25).

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

details needs the OpenAlex id stored with the record; records without one are refused.

Examples

Most cited

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/academic.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"transformer attention","sort":"cited","num":5}'

Recent open access

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/academic.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"protein folding","from_year":2024,"open_access_only":true}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the AcademicSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of academic.search
Key	Type	Presence
year	integer	when the source has it
venue	string	when the source has it
authors	string[]	when the source has it
cited_by	integer	when the source has it
type	string	when the source has it
open_access	boolean	when the source has it
oa_url	string	when the source has it
doi	string	when the source has it
openalex_id	string	always

Follow-ups

Paging: Provider page number; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (AcademicSearchUpdateParams).
Record actions:
- details: Abstract, citation counts, open-access PDF and landing page.
Detail behaviour: Free provider lookup on first call; repeats are cached. details is a free OpenAlex work lookup; repeated calls are cached.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/academic.search/execute", {
  body: {
    "query": "transformer attention",
    "sort": "cited",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);