API Reference

Auto-generated API documentation for aletheca's public modules.

Session

High-level session manager for interacting with the OpenAlex API.

Usage::

async with AlethecaSession() as session:
    works = await session.works.search(
        search="machine learning"
    )
    for work in works.results:
        print(work.title)

# With API key
async with AlethecaSession(api_key="...") as session:
    count = await session.works.count()

queries property

Access convenience query functions.

__init__(settings=None, *, api_key=None, base_url=None)

Initialize the AlethecaSession.

Parameters:

Name	Type	Description	Default
settings	AlethecaSettings | None	Optional AlethecaSettings. If None, loads from env.	None
api_key	str | None	Optional OpenAlex API key (overrides settings).	None
base_url	str | None	Optional API base URL override.	None

close() async

Close the underlying HTTP client session.

Client

Bases: BaseApiClient

Asynchronous client for the OpenAlex API.

Provides access to all OpenAlex entity endpoints through typed resource client properties.

Usage::

async with AlethecaClient() as client:
    work = await client.works.get("W1234567890")

works property

Access the Works endpoint client.

authors property

Access the Authors endpoint client.

sources property

Access the Sources endpoint client.

institutions property

Access the Institutions endpoint client.

topics property

Access the Topics endpoint client.

keywords property

Access the Keywords endpoint client.

publishers property

Access the Publishers endpoint client.

funders property

Access the Funders endpoint client.

__init__(settings=None, *, api_key=None, base_url=None, auth_strategy=None)

Initialize the AlethecaClient.

Parameters:

Name	Type	Description	Default
settings	AlethecaSettings | None	Optional AlethecaSettings instance. If None, loads from env.	None
api_key	str | None	Optional OpenAlex API key (overrides settings). Ignored when auth_strategy is also provided.	None
base_url	str | None	Optional API base URL override.	None
auth_strategy	AuthStrategy | None	Optional auth strategy override. When provided, takes precedence over api_key.	None

Configuration

Bases: BaseApiSettings

OpenAlex-specific settings.

Inherits all generic API client settings from BaseApiSettings and adds OpenAlex-specific configuration.

Settings are loaded from environment variables (prefixed with 'ALETHECA_') or .env/secrets.env files.

Endpoint Filters

Bases: BaseModel

Filter model for the Works endpoint.

OpenAlex filter syntax: filter=field:value,field:value Nested fields use dot notation via Pydantic aliases.

Bases: BaseModel

Filter model for the Authors endpoint.

Bases: BaseModel

Filter model for the Sources endpoint.

Bases: BaseModel

Filter model for the Institutions endpoint.

Bases: BaseModel

Filter model for the Topics endpoint.

Bases: BaseModel

Filter model for the Keywords endpoint.

Bases: BaseModel

Filter model for the Publishers endpoint.

Bases: BaseModel

Filter model for the Funders endpoint.

Resource Clients

Bases: GettableMixin, SearchableMixin, CursorIterableMixin, AlethecaResourceClient

Client for the OpenAlex Works API endpoint.

Supports GET by ID (including DOI/PMID), search, cursor iteration, full-text search, filtering, and sorting.

Bases: StandardResourceClient

Client for the OpenAlex Authors API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Sources API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Institutions API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Topics API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Keywords API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Publishers API endpoint.

Bases: StandardResourceClient

Client for the OpenAlex Funders API endpoint.

Convenience Queries

Convenience query functions for common OpenAlex workflows.

These functions accept an AlethecaSession as their first argument and compose multiple API calls into higher-level operations.

Access via session.queries.function_name(...).

works_by_author(session, author_name, *, limit=None) async

Get works by an author (searches by name, then fetches their works).

Parameters:

Name	Type	Description	Default
session	AlethecaSession	Active AlethecaSession.	required
author_name	str	Author display name to search for.	required
limit	int | None	Max number of works to return.	None

Returns:

Type	Description
list[Work]	List of Work entities.

works_by_institution(session, institution_name, *, limit=None) async

Get works affiliated with an institution.

Parameters:

Name	Type	Description	Default
session	AlethecaSession	Active AlethecaSession.	required
institution_name	str	Institution display name to search for.	required
limit	int | None	Max number of works to return.	None

Returns:

Type	Description
list[Work]	List of Work entities.

works_by_doi(session, dois) async

Fetch works by their DOIs.

Parameters:

Name	Type	Description	Default
session	AlethecaSession	Active AlethecaSession.	required
dois	list[str]	List of DOI strings (with or without https://doi.org/ prefix).	required

Returns:

Type	Description
list[Work]	List of Work entities.

citing_works(session, work_id, *, limit=None) async

Get works that cite a given work.

Parameters:

Name	Type	Description	Default
session	AlethecaSession	Active AlethecaSession.	required
work_id	str	OpenAlex work ID (e.g., W1234567890).	required
limit	int | None	Max number of works to return.	None

Returns:

Type	Description
list[Work]	List of citing Work entities.

referenced_works(session, work_id, *, limit=None) async

Get works referenced by a given work.

Parameters:

Name	Type	Description	Default
session	AlethecaSession	Active AlethecaSession.	required
work_id	str	OpenAlex work ID (e.g., W1234567890).	required
limit	int | None	Max number of works to return.	None

Returns:

Type	Description
list[Work]	List of referenced Work entities.

Helpers

Utility helpers for working with OpenAlex identifiers and data.

normalize_doi(doi)

Normalize a DOI to its bare form (no URL prefix).

Parameters:

Name	Type	Description	Default
doi	str	A DOI string, possibly with https://doi.org/ prefix.	required

Returns:

Type	Description
str	The bare DOI string.

Examples:

>>> normalize_doi("https://doi.org/10.1234/x")
"10.1234/x"
>>> normalize_doi("10.1234/x")
"10.1234/x"

parse_openalex_id(url_or_id)

Extract the short OpenAlex ID from a full URL or bare ID.

Parameters:

Name	Type	Description	Default
url_or_id	str	An OpenAlex ID or URL (e.g., https://openalex.org/W123).	required

Returns:

Type	Description
str	The short ID (e.g., W123).

Examples:

>>> parse_openalex_id("https://openalex.org/W1234567890")
"W1234567890"
>>> parse_openalex_id("W1234567890")
"W1234567890"

detect_id_type(identifier)

Detect the type of a scholarly identifier.

Parameters:

Name	Type	Description	Default
identifier	str	A string identifier.	required

Returns:

Type	Description
str | None	One of "openalex", "doi", "pmid", "orcid",
str | None	"issn", "ror", or None.

reconstruct_abstract(inverted_index)

Reconstruct an abstract from OpenAlex's inverted index format.

Parameters:

Name	Type	Description	Default
inverted_index	dict[str, list[int]] | None	Mapping of word → list of positions.	required

Returns:

Type	Description
str | None	The reconstructed abstract string, or None if input is None/empty.

Models

Bases: BaseEntity

An OpenAlex Work entity.

reconstructed_abstract property

Reconstruct the full abstract text from the inverted index.

Bases: BaseEntity

An OpenAlex Author entity.

Bases: BaseEntity

An OpenAlex Source entity (journal, repository, conference, etc.).

Bases: BaseEntity

An OpenAlex Institution entity.

Bases: BaseEntity

An OpenAlex Topic entity.

Bases: BaseEntity

An OpenAlex Keyword entity.

Bases: BaseEntity

An OpenAlex Publisher entity.

Bases: BaseEntity

An OpenAlex Funder entity.

Bases: BaseModel

Generic envelope for OpenAlex list/search responses.

Bases: BaseModel

Base model for all OpenAlex entities.

All OpenAlex entities share id and display_name fields. Most also have works_count and cited_by_count.