canonical: https://jentic.com/apis/moodle.org/moodle

# Moodle Web Services API

Jentic publishes the only available OpenAPI specification for Moodle Web Services API, keeping it validated and agent-ready. Exposes 90 RPC-style web service functions for managing users, courses, enrollments, grades, assignments, quizzes, forums, calendar events, messages, competencies, and file uploads on self-hosted Moodle instances. Authentication uses a wstoken passed as a query parameter, obtained from the /login/token.php endpoint. Supports Moodle 4.5 with coverage across core subsystems including course completion tracking and competency frameworks.

## For AI agents

Execute 90 Moodle web service functions covering user management, course operations, grading, assignments, quizzes, forum posts, messaging, and calendar events on any Moodle 4.5 instance.

## Scope

Does not handle Moodle plugin installation, theme customization, or server administration - use for web service data operations only.

## Capabilities

- Enroll and unenrol users from courses with automatic role assignment
- Retrieve and submit assignment grades with feedback across all course participants
- Search and create courses with full metadata including categories and timelines
- Send messages to conversations and manage user blocking and read receipts
- Track activity completion and course completion status per user
- Upload files and manage course content modules programmatically
- Query competency frameworks and evaluate user competency progress

## Use cases

### AI Agent Course and Enrollment Management

AI agents use the Moodle Web Services API through Jentic to automate course creation, user enrollment, and role assignment on self-hosted Moodle instances. The agent searches for enrollment functions like enrol_manual_enrol_users, loads the parameter schema, and executes without navigating Moodle's web service plugin configuration. This enables automated provisioning of courses and cohorts at the start of each academic term across institutions running Moodle 4.5.

Example prompt: Enroll user ID 42 in course ID 7 with the student role using the enrol_manual_enrol_users web service function

### Assignment Grading and Feedback Workflow

Programmatically retrieve assignment submissions, apply grades, and submit feedback across entire courses. The mod_assign_get_submissions function returns all student submissions for an assignment, mod_assign_get_grades retrieves existing grades, and mod_assign_save_grade saves a new grade with feedback. This supports automated grading pipelines and bulk feedback distribution for courses with hundreds of students.

Example prompt: Retrieve submissions for assignment module in course 15 via mod_assign_get_submissions, then save a grade of 85 with feedback using mod_assign_save_grade

### Student Progress Tracking and Completion

Monitor student progress through courses by querying activity completion status, course completion records, and grade reports. The core_completion_get_activities_completion_status function returns completion state for all activities in a course, while gradereport_user_get_grade_items provides the full grade breakdown. This enables early-intervention dashboards that identify students falling behind.

Example prompt: Check completion status for user 99 in course 20 using core_completion_get_course_completion_status and list incomplete activities via core_completion_get_activities_completion_status

### Forum and Messaging Automation

Automate forum participation monitoring and direct messaging within Moodle. The mod_forum_get_forum_discussions function lists all discussion threads, mod_forum_get_discussion_posts retrieves replies, and mod_forum_add_discussion creates new threads. The messaging subsystem supports sending instant messages, retrieving conversations, and managing read state across 90 web service endpoints.

Example prompt: Post a new discussion titled 'Week 5 Assignment Q&A' in the forum for course 12 using mod_forum_add_discussion

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /webservice/rest/enrol_manual_enrol_users | Enroll users in courses with role assignment |
| POST | /webservice/rest/core_course_create_courses | Create new courses with metadata |
| POST | /webservice/rest/core_course_search_courses | Search courses by keyword |
| POST | /webservice/rest/mod_assign_get_submissions | Get all submissions for an assignment |
| POST | /webservice/rest/mod_assign_save_grade | Save a grade with feedback for a submission |
| POST | /webservice/rest/core_user_create_users | Create new user accounts in bulk |
| POST | /webservice/rest/gradereport_user_get_grade_items | Get grade items for a user in a course |
| POST | /login/token.php | Obtain a web service token for authentication |

## Key resources

- **Users** — Create, retrieve, update, and delete user accounts with profile preferences
- **Courses** — Create, search, update, and delete courses with category and timeline management
- **Enrollments** — Manually enroll and unenrol users with role assignments and self-enrollment
- **Assignments** — Retrieve assignments, submissions, and grades with feedback submission support
- **Grades** — Access grade reports, grade items, and grade tables per user and course
- **Calendar** — Create, retrieve, and delete calendar events with timeline views
- **Messages** — Send instant messages, manage conversations, block/unblock users
- **Competencies** — Query competency frameworks, plans, and user competency evaluations

## Why Jentic

- **Setup:** Wiring Moodle by hand means minting a web service token, targeting your own instance host, and passing the wstoken as a query parameter on every REST function call. Through Jentic you install once, import the Moodle Web Services API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Moodle addresses each action by function name rather than a resource path, so limit the agent to the operations it needs, such as searching courses or reading grade items. You choose the operations it may call, so writes like creating users or saving grades are not included unless you add them.
- **Credential handling:** Your Moodle web service token is stored once, encrypted, by your own Jentic One instance and injected as the wstoken parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'enroll a user in a Moodle course' or 'read a student's grades', and Jentic returns the matching Moodle web service function with its parameter schema, so the agent calls the right function without navigating Moodle's plugin documentation.

## Related APIs

- **Schoology REST API** — Schoology is a commercial K-12 LMS with RESTful endpoints; Moodle is open-source with RPC-style web services
- **D2L Brightspace Valence API** — Brightspace is a commercial LMS focused on higher education; Moodle is open-source and self-hosted
- **Clever Data API** — Clever provides read-only SIS roster data; Moodle handles full LMS operations including course content and grading

## FAQ

### Why is there no official OpenAPI spec for Moodle Web Services API?

Moodle does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Moodle Web Services API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Moodle Web Services API use?

Moodle uses an API key (wstoken) passed as a query parameter on every request. Tokens are obtained from the /login/token.php endpoint using username and password credentials plus the service shortname. Through Jentic, the wstoken is stored in the encrypted Jentic One instance, so agents authenticate without handling raw credentials.

### Can I enroll users in a Moodle course with the API?

Yes. Use the enrol_manual_enrol_users function, which accepts an array of enrollments each specifying a user ID, course ID, and role ID (5 for student, 3 for teacher). You can also use enrol_manual_unenrol_users to remove enrollments or enrol_self_enrol_user for self-service enrollment.

### How do I retrieve assignment grades for a student through Jentic?

Search Jentic for 'get moodle assignment grades' to find the gradereport_user_get_grade_items function. This returns all grade items for a specific user in a course, including assignment grades, quiz scores, and computed totals. Install with pip install jentic, then search, load the schema, and execute with the user and course IDs.

### What are the rate limits for the Moodle Web Services API?

Rate limits depend on the Moodle instance configuration set by the site administrator. There are no universal limits in the spec. Administrators typically configure request throttling via the Moodle security settings. Self-hosted instances can adjust these limits based on server capacity.

### Does the Moodle API support file uploads?

Yes. The core_files_upload function handles file uploads to Moodle's file system. You provide the file content, filename, and target context (course, user, etc.). The core_files_get_files function retrieves file listings from any file area in the system.

### Can I limit what my agent is allowed to do with the Moodle Web Services API?

Yes. Because Moodle addresses each action by function name rather than a resource path, your self-hosted Jentic One instance lets you allow only the specific functions your agent needs, such as core_course_search_courses or gradereport_user_get_grade_items for read-only work. Write functions like enrol_manual_enrol_users, core_user_create_users, or mod_assign_save_grade stay off-limits unless you explicitly add them. Your own rules decide which operations the agent may call and which stored wstoken it uses, so the agent never has access beyond what you grant.