API reference

Package exports

pyedstem

Public package exports for pyedstem.

EdStemClient

High-level synchronous client for the Ed Stem API.

This is the main entry point for the library. It owns a shared HTTP transport and exposes grouped resource clients for the supported endpoint areas, such as courses, threads, lessons, analytics, challenges, and the authenticated user.

Parameters:

Name	Type	Description	Default
api_token	str	Ed Stem API bearer token.	required
base_url	str	Base URL for the Ed Stem API. Defaults to the public hosted API endpoint.	'https://edstem.org/api'
timeout_seconds	float	Request timeout applied to the underlying HTTP client.	30.0
http_client	Client | None	Optional preconfigured httpx.Client. When provided, it is used directly instead of constructing a new client.	None

Attributes:

Name	Type	Description
user		User-related endpoints.
courses		Course metadata and course-scoped collections.
threads		Discussion thread listing, search, detail lookup, and answer posting.
lessons		Lesson, slide, and result endpoints.
analytics		Course analytics endpoints.
challenges		Course challenge listing endpoints.

__enter__()

Enter a context-managed client session.

Returns:

Type	Description
'EdStemClient'	The current client instance.

__exit__(exc_type, exc, tb)

Close HTTP resources when leaving a context manager.

Parameters:

Name	Type	Description	Default
exc_type	object	Exception type raised inside the context, if any.	required
exc	object	Exception instance raised inside the context, if any.	required
tb	object	Traceback associated with the exception, if any.	required

close()

Close the underlying HTTP transport.

Call this method when the client is no longer needed, unless the client is already being managed via a with statement.

from_env() classmethod

Create a client from environment-backed settings.

The settings are loaded from EDSTEM_* environment variables and, by default, from a local .env file.

Returns:

Type	Description
'EdStemClient'	A configured EdStemClient instance.

Raises:

Type	Description
ValidationError	If required settings such as EDSTEM_API_TOKEN are missing or invalid.

get_json(path, *, params=None)

Perform a raw JSON GET request for less common endpoints.

This is a convenience escape hatch for endpoints that are not yet wrapped by a first-class resource method.

Parameters:

Name	Type	Description	Default
path	str	API path relative to the configured base URL, for example "/courses/123/resources".	required
params	dict[str, Any] | None	Optional query-string parameters.	None

Returns:

Type	Description
dict[str, Any]	The decoded JSON response body as a dictionary.

Raises:

Type	Description
AuthenticationError	If the API token is rejected.
NotFoundError	If the requested endpoint or resource does not exist.
RateLimitError	If the API rate-limits the request.
ValidationError	If Ed rejects the request as invalid.
ServerError	If Ed returns a server-side failure.

Client

pyedstem.client.EdStemClient

High-level synchronous client for the Ed Stem API.

This is the main entry point for the library. It owns a shared HTTP transport and exposes grouped resource clients for the supported endpoint areas, such as courses, threads, lessons, analytics, challenges, and the authenticated user.

Parameters:

Name	Type	Description	Default
api_token	str	Ed Stem API bearer token.	required
base_url	str	Base URL for the Ed Stem API. Defaults to the public hosted API endpoint.	'https://edstem.org/api'
timeout_seconds	float	Request timeout applied to the underlying HTTP client.	30.0
http_client	Client | None	Optional preconfigured httpx.Client. When provided, it is used directly instead of constructing a new client.	None

Attributes:

Name	Type	Description
user		User-related endpoints.
courses		Course metadata and course-scoped collections.
threads		Discussion thread listing, search, detail lookup, and answer posting.
lessons		Lesson, slide, and result endpoints.
analytics		Course analytics endpoints.
challenges		Course challenge listing endpoints.

__enter__()

Enter a context-managed client session.

Returns:

Type	Description
'EdStemClient'	The current client instance.

__exit__(exc_type, exc, tb)

Close HTTP resources when leaving a context manager.

Parameters:

Name	Type	Description	Default
exc_type	object	Exception type raised inside the context, if any.	required
exc	object	Exception instance raised inside the context, if any.	required
tb	object	Traceback associated with the exception, if any.	required

close()

Close the underlying HTTP transport.

Call this method when the client is no longer needed, unless the client is already being managed via a with statement.

from_env() classmethod

Create a client from environment-backed settings.

The settings are loaded from EDSTEM_* environment variables and, by default, from a local .env file.

Returns:

Type	Description
'EdStemClient'	A configured EdStemClient instance.

Raises:

Type	Description
ValidationError	If required settings such as EDSTEM_API_TOKEN are missing or invalid.

get_json(path, *, params=None)

Perform a raw JSON GET request for less common endpoints.

This is a convenience escape hatch for endpoints that are not yet wrapped by a first-class resource method.

Parameters:

Name	Type	Description	Default
path	str	API path relative to the configured base URL, for example "/courses/123/resources".	required
params	dict[str, Any] | None	Optional query-string parameters.	None

Returns:

Type	Description
dict[str, Any]	The decoded JSON response body as a dictionary.

Raises:

Type	Description
AuthenticationError	If the API token is rejected.
NotFoundError	If the requested endpoint or resource does not exist.
RateLimitError	If the API rate-limits the request.
ValidationError	If Ed rejects the request as invalid.
ServerError	If Ed returns a server-side failure.

User resources

pyedstem.resources.user.User

Access user-centric Ed endpoints for the authenticated account.

get_activity(user_id, *, course_id, limit, filter_by)

Fetch recent activity for one user in a course.

Parameters:

Name	Type	Description	Default
user_id	int	Numeric Ed user identifier.	required
course_id	int	Numeric Ed course identifier used to scope the activity.	required
limit	int	Maximum number of activity items to request.	required
filter_by	str	Ed activity filter string forwarded as the filter query parameter.	required

Returns:

Type	Description
list[dict]	A list of raw activity item dictionaries.

get_current_user()

Fetch the authenticated user profile and enrollments.

Returns:

Type	Description
CurrentUserResponse	A validated CurrentUserResponse model containing the current
CurrentUserResponse	user plus enrolled courses.

list_tokens()

List API tokens visible to the authenticated user.

Returns:

Type	Description
list[dict]	A list of raw token dictionaries returned by Ed.

Course resources

pyedstem.resources.courses.Courses

Access course endpoints and course-scoped collections.

Methods on this resource cover both direct course metadata and related collections such as enrolled users, labs, groups, resources, bots, and workspaces.

get(course_id)

Fetch detailed metadata for one course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
CourseInfo	A validated CourseInfo model for the requested course.

get_admin(course_id)

Fetch course admin metadata.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON payload from GET /courses/{course_id}/admin.

get_stats(course_id)

Fetch high-level course statistics.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
dict[str, Any]	The stats object from the endpoint response, or an empty
dict[str, Any]	dictionary if the key is absent.

list_active()

Return only courses marked active by Ed.

This method derives its result from the authenticated user's GET /user payload rather than from a dedicated active-courses endpoint.

Returns:

Type	Description
list[CourseInfo]	A list of CourseInfo objects whose status is "active".

list_bots(course_id)

List course AI bots.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of bot dictionaries returned by Ed.

list_groups(course_id)

List course groups.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of group dictionaries returned by Ed.

list_labs(course_id)

List course labs or tutorials.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of lab dictionaries returned by Ed.

list_resources(course_id)

List course resources.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of resource dictionaries returned by Ed.

list_users(course_id, *, limit=None)

List users enrolled in a course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required
limit	int | None	Optional maximum number of users to request.	None

Returns:

Type	Description
list[UserSummary]	A list of validated UserSummary models.

list_workspaces(course_id)

List course workspace metadata.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON response from the workspaces endpoint.

Thread resources

pyedstem.resources.threads.Threads

Access discussion thread listing, search, detail, and answer posting.

This resource wraps the main discussion endpoints used for reading course threads and posting staff answers.

get(thread_id)

Fetch full details for one thread.

Parameters:

Name	Type	Description	Default
thread_id	int	Global Ed thread identifier.	required

Returns:

Type	Description
ThreadDetail	A validated ThreadDetail model including answers and comments.

get_by_number(course_id, thread_number)

Fetch a course thread by its course-local thread number.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required
thread_number	int	Thread number as displayed within the course.	required

Returns:

Type	Description
ThreadDetail	A validated ThreadDetail model for the matching thread.

iter_all(course_id, *, limit=50, sort='date', **filters)

Iterate through all available paginated thread results.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required
limit	int	Page size for each underlying list request.	50
sort	str	Sort mode understood by Ed, such as "date".	'date'
**filters	Any	Additional query-string filters forwarded directly to each list request.	{}

Yields:

Type	Description
ThreadSummary	ThreadSummary objects one at a time until the endpoint is
ThreadSummary	exhausted.

list(course_id, *, limit=20, offset=0, sort='date', **filters)

Fetch one page of threads for a course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required
limit	int	Maximum number of threads to return.	20
offset	int	Pagination offset for the result page.	0
sort	str	Sort mode understood by Ed, such as "date".	'date'
**filters	Any	Additional query-string filters forwarded directly to the endpoint, for example filter="unanswered".	{}

Returns:

Type	Description
List[ThreadSummary]	A list of validated ThreadSummary models.

post_answer(*, thread_id, markdown, is_anonymous=False, is_private=False)

Post an answer to a thread using markdown input.

The markdown is converted into the XML document format expected by the Ed comments endpoint.

Parameters:

Name	Type	Description	Default
thread_id	int	Global Ed thread identifier.	required
markdown	str	Answer body written in markdown.	required
is_anonymous	bool	Whether the answer should be posted anonymously.	False
is_private	bool	Whether the answer should be visible only to staff and the thread author.	False

Returns:

Type	Description
PostedComment	A validated PostedComment model representing the created
PostedComment	answer or comment object returned by Ed.

search(course_id, *, query)

Search for threads in a course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required
query	str	Free-text search string.	required

Returns:

Type	Description
List[ThreadSummary]	A list of validated ThreadSummary models matching the query.

Lesson resources

pyedstem.resources.lessons.Lessons

Access lesson, slide, activity, and result endpoints.

get(lesson_id)

Fetch full lesson details including slides.

Parameters:

Name	Type	Description	Default
lesson_id	int	Numeric Ed lesson identifier.	required

Returns:

Type	Description
LessonDetail	A validated LessonDetail model.

get_activity(lesson_id)

Fetch lesson activity logs.

Parameters:

Name	Type	Description	Default
lesson_id	int	Numeric Ed lesson identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON activity payload for the lesson.

get_slide(slide_id)

Fetch one slide by ID.

Parameters:

Name	Type	Description	Default
slide_id	int	Numeric Ed slide identifier.	required

Returns:

Type	Description
SlideSummary	A validated SlideSummary model.

get_slide_questions(slide_id)

Fetch quiz questions for one slide.

Parameters:

Name	Type	Description	Default
slide_id	int	Numeric Ed slide identifier.	required

Returns:

Type	Description
List[Dict[str, Any]]	A list of raw question dictionaries returned by Ed.

get_slide_results(slide_id)

Fetch quiz results for one slide.

Parameters:

Name	Type	Description	Default
slide_id	int	Numeric Ed slide identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON payload returned by the slide results endpoint.

list(course_id)

List lessons for a course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
List[LessonSummary]	A list of validated LessonSummary models.

list_results(lesson_id, *, user_id=None, limit=None)

Fetch lesson result rows.

Parameters:

Name	Type	Description	Default
lesson_id	int	Numeric Ed lesson identifier.	required
user_id	int | None	Optional user filter for per-user results.	None
limit	int | None	Optional maximum number of result rows.	None

Returns:

Type	Description
List[Dict[str, Any]]	A list of raw result dictionaries returned by Ed.

list_slides(lesson_id)

List slides for a lesson.

Parameters:

Name	Type	Description	Default
lesson_id	int	Numeric Ed lesson identifier.	required

Returns:

Type	Description
List[SlideSummary]	A list of validated SlideSummary models.

Analytics resources

pyedstem.resources.analytics.Analytics

Access course analytics endpoints.

These endpoints return lightly structured analytics payloads, so the methods currently expose raw dictionaries and lists.

get_challenges(course_id)

Fetch challenge analytics.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON payload for course challenge analytics.

get_discussion(course_id)

Fetch discussion analytics.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
dict[str, Any]	The decoded JSON payload for course discussion analytics.

get_users(course_id)

Fetch user analytics rows.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of raw user analytics rows.

Challenge resources

pyedstem.resources.challenges.Challenges

Access challenge listing endpoints.

list(course_id)

List challenges for a course.

Parameters:

Name	Type	Description	Default
course_id	int	Numeric Ed course identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	A list of raw challenge dictionaries returned by Ed.

Content helpers

pyedstem.content

Helpers for converting content into Ed-compatible formats.

html_to_markdown(content)

Convert Ed HTML content into markdown.

This is mainly useful when exporting or staging existing Ed thread content for local review and editing.

Parameters:

Name	Type	Description	Default
content	str	HTML content returned by Ed.	required

Returns:

Type	Description
str	A markdown representation of the HTML content with ATX headings.

markdown_to_ed_document(markdown)

Convert markdown into the Ed XML document format used by comments.

The converter currently preserves plain paragraphs and fenced code blocks. Non-code text is split into paragraph elements, while fenced blocks are emitted as Ed codeblock elements.

Parameters:

Name	Type	Description	Default
markdown	str	Markdown source to convert.	required

Returns:

Type	Description
str	A string containing an Ed <document version="2.0"> payload.
str	Blank input produces a minimal empty paragraph document.

Data models

pyedstem.models

Typed data models for pyedstem.

CommentSummary

Bases: FlexibleModel

Thread answer/comment representation.

Attributes:

Name	Type	Description
id	int	Numeric comment identifier.
type	str | None	Ed comment type such as "answer" or "comment".
content	str | None	Raw Ed content payload, usually HTML or XML-like markup.
user_id	int | None	Identifier of the comment author.
created_at	str | None	Creation timestamp, when present.

CourseEnrollment

Bases: FlexibleModel

Course membership information from GET /user.

Attributes:

Name	Type	Description
course	CourseInfo	Embedded course metadata.
role	str | None	The authenticated user's role in the course.
lab	str | None	Lab or tutorial assignment, when present.
last_active	str | None	Timestamp for recent course activity, when present.

CourseInfo

Bases: FlexibleModel

Core course metadata.

Attributes:

Name	Type	Description
id	int	Numeric Ed course identifier.
code	str | None	Course code such as QBUS6860.
name	str | None	Human-readable course name.
status	str | None	Course status, for example "active" or "archived".
year	str | None	Academic year, when provided.
session	str | None	Session or term label, when provided.

CurrentUser

Bases: FlexibleModel

Authenticated user profile.

Attributes:

Name	Type	Description
id	int	Numeric Ed user identifier.
name	str | None	Display name.
role	str | None	Global or contextual Ed role, when present.
email	str | None	User email address, when present.
username	str | None	Ed username, when present.

CurrentUserResponse

Bases: FlexibleModel

Typed response payload for GET /user.

Attributes:

Name	Type	Description
user	CurrentUser	Authenticated user profile.
courses	list[CourseEnrollment]	Course enrollments visible to the authenticated user.
realms	list[dict[str, Any]]	Additional realm/account metadata returned by Ed.

FlexibleModel

Bases: BaseModel

Base model that tolerates undocumented response fields.

Ed Stem responses may include fields that are undocumented or vary between endpoints. Models inherit from this base so extra keys do not break parsing.

LessonDetail

Bases: LessonSummary

Expanded lesson detail payload.

Attributes:

Name	Type	Description
slides	list[SlideSummary]	Slide summaries included in the lesson detail response.

LessonSummary

Bases: FlexibleModel

Lesson summary metadata.

Attributes:

Name	Type	Description
id	int	Numeric Ed lesson identifier.
title	str | None	Lesson title.
course_id	int | None	Owning course identifier.
module_id	int | None	Owning module identifier, when present.
slide_count	int | None	Number of slides, when present.

PostedComment

Bases: FlexibleModel

Representation of a posted answer or comment.

Attributes:

Name	Type	Description
id	int	Numeric comment identifier.
type	str | None	Ed comment type.
content	str | None	Raw returned content payload.
user_id	int | None	Identifier of the comment author.
created_at	str | None	Creation timestamp, when present.

SlideSummary

Bases: FlexibleModel

Lesson slide metadata.

Attributes:

Name	Type	Description
id	int	Numeric Ed slide identifier.
title	str | None	Slide title.
type	str | None	Slide type such as "quiz".
lesson_id	int | None	Owning lesson identifier.
challenge_id	int | None	Linked challenge identifier, when present.

ThreadDetail

Bases: ThreadSummary

Thread detail with answers and comments.

Attributes:

Name	Type	Description
answers	list[CommentSummary]	Answer objects attached to the thread.
comments	list[CommentSummary]	Non-answer comments attached to the thread.

ThreadSummary

Bases: FlexibleModel

Thread summary returned from list endpoints.

Attributes:

Name	Type	Description
id	int	Global Ed thread identifier.
number	int	Course-local thread number.
course_id	int	Numeric Ed course identifier.
title	str	Thread title.
type	str	Thread type such as "question".
category	str | None	Optional category label.
content	str | None	Raw thread content snippet, when present.
user_id	int	Identifier of the thread author.
is_answered	bool	Whether the thread is marked answered.
is_staff_answered	bool	Whether staff has answered the thread.
deleted_at	str | None	Deletion timestamp, if the thread was deleted.
created_at	str | None	Creation timestamp, when present.

UserSummary

Bases: FlexibleModel

Minimal user details used across multiple endpoints.

Attributes:

Name	Type	Description
id	int	Numeric Ed user identifier.
name	str | None	Display name for the user.
role	str | None	Course or platform role, when present.
email	str | None	User email address, when exposed by the endpoint.
username	str | None	Ed username, when available.