Repository navigation
Description
RFC Start Date
N/A -- Already Accepted
Target Plan Accepted Date
N/A -- Already Accepted
Target Transition Unblocked Date
Immediately -- Transition Already Unblocked
Earliest Breaking Changes Unblocked Date
One named release after the release this deprecation ships in
Rationale
As part of FC-0118 (API standardization), a set of Studio contentstore
endpoints and the LMS enrollment API were re-issued at new versions rather than
changed in place. The standardization ADRs mandate changes that are breaking for
existing consumers:
- ADR 0029 replaces the legacy
{"developer_message": ..., "error_code": ...}
error shape with an RFC 7807 envelope (type,title,status,detail,
instance). Any client parsing error responses would break. - ADR 0028 moves from
APIViewtoViewSet+DefaultRouter, changing URL
patterns (trailing slashes, router-managed routing). - ADR 0026 standardizes authentication and removes the deprecated
BearerAuthentication, so Bearer-only consumers lose access. - ADR 0032 standardizes pagination, changing the response envelope on list
endpoints.
Issuing new versions let existing consumers migrate on their own timeline
instead of absorbing a silent breaking change. That migration window is what
this ticket closes: the old versions are now redundant, and keeping both means
every future change to these endpoints has to be made twice.
Description
All replacements are merged and available today via
#38755.
| Deprecated endpoint | Replacement | Standardization issue |
|---|---|---|
GET/POST /api/contentstore/v0/xblock/{course_id} and /{course_id}/{usage_key} |
GET/POST/PATCH/DELETE /api/contentstore/v1/xblock/{usage_key}/ |
#38368 |
/api/enrollment/v1/ — enrollment, enrollments, course/{course_id}, unenroll/, roles/, enrollment_allowed/ |
/api/enrollment/v2/ |
#38369 |
GET/PUT /api/contentstore/v1/course_details/{course_id} |
GET/PUT /api/contentstore/v3/course_details/{course_key}/ |
#38370 |
GET /api/contentstore/v1/home |
GET /api/contentstore/v3/home/ |
#38371 |
GET /api/contentstore/v2/home/courses |
GET /api/contentstore/v4/home/ |
#38372 |
POST /api/contentstore/v0/grading/{course_id} |
PATCH /api/contentstore/v3/authoring_grading/{course_key}/ |
#38373 |
Consumers migrating should expect the RFC 7807 error envelope, router-managed
URLs (note the trailing slash), JWT or session auth in place of Bearer, and on
list endpoints the standardized pagination envelope.
Deprecation Schedule
The old versions are deprecated as of this ticket and will be removed one
named release after the release in which this deprecation ships, giving
operators and plugin authors a full release cycle on a supported version.
- Now — endpoints marked deprecated:
deprecated: truein the OpenAPI
schema, aWarningresponse header, and docs pointing at the replacements. - Next named release — both versions ship; the deprecated ones still work.
- The release after — old versions removed.
Task List
This ticket is the umbrella for API deprecations arising from the FC-0118
standardization work. Further areas will be appended as their replacement
versions merge:
- contentstore xblock, course_details, home (v1 and v2), grading; LMS enrollment v1 — #38755
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDraft
Activity
fix: keep the v0 video upload deprecation out of the superseded code
Abdul-Muqadim-Arbisoft commentedon Sep 27, 2026
Entry for this ticket: contentstore video uploads. The replacement is in review in #39102; please add the lines below when it merges.
Rows for the Description table:
POST /api/contentstore/v0/videos/uploads/{course_id}POST /api/authoring/v1/courses/{course_key}/videos/GET/DELETE /api/contentstore/v0/videos/uploads/{course_id}/{edx_video_id}GET /api/authoring/v1/courses/{course_key}/videos/(the listing the v0 GET returns) andGET/DELETE /api/authoring/v1/courses/{course_key}/videos/{edx_video_id}/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.The timeline is this ticket's: removed one named release after the release this ships in.
Abdul-Muqadim-Arbisoft commentedon Oct 4, 2026
Entry for this ticket: contentstore video management. The replacement is in review in #39186; please add the lines below when it merges.
Rows for the Description table:
GET /api/contentstore/v1/videos/{course_id}/{edx_video_id}/usageGET /api/authoring/v2/courses/{course_key}/video_usages/{edx_video_id}/PUT /api/contentstore/v1/videos/{course_id}/downloadPOST /api/authoring/v2/courses/{course_key}/video_archives/Line for the Task List:
Removal step for this area: move
VideoDownloadThrottleout ofcms/djangoapps/contentstore/rest_api/v1/views/videos.pybefore that module is deleted. The v2 archive view and its tests import it from there, so deleting the module first breaks the import ofcms/urls.py.How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.The timeline is this ticket's: removed one named release after the release this ships in.
taimoor-ahmed-1 commentedon Oct 13, 2026
Entry for this ticket: contentstore course grading. The replacement is in review in #39227; please add the lines below when it merges.
Rows for the Description table:
GET/POST /api/contentstore/v1/course_grading/{course_id}GET/PATCH /api/authoring/v3/courses/{course_key}/grading/GET/PATCH /api/contentstore/v3/authoring_grading/{course_key}/GET/PATCH /api/authoring/v3/courses/{course_key}/grading/The existing
POST /api/contentstore/v0/grading/{course_id}row should point at the same replacement,PATCH /api/authoring/v3/courses/{course_key}/grading/. #39227 also marks that v0 route deprecated in the CMS schema, which it was not until now.Line for the Task List:
Migration notes
course_details.?view=fulladdscourse_assignment_lists,default_grade_designations,is_credit_course,show_credit_eligibilityandmfe_proctored_exam_settings_url, under the v1 names.grace_periodalso gainsseconds.minimum_grade_creditmust be JSON numbers (a string, including"", is refused with 400), gradertypeandshort_labelmust be strings andgradersa list. v1 and v0 store those bodies as sent. PATCH also accepts partial bodies, changing only the fields sent.How it is marked:
deprecated: truein the CMS schema, plus a docstring note on the v1 and v0 views. No response header.Window: this ticket's own schedule. The marking ships in the next named release after Verawood, and the deprecated addresses are removed one named release after that.
taimoor-ahmed-1 commentedon Oct 14, 2026
Entry for this ticket: contentstore course index. The replacement is in review in #39229; please add the lines below when it merges.
Rows for the Description table:
GET /api/contentstore/v1/course_index/{course_id}GET /api/authoring/v2/courses/{course_key}/outline/?view=full(the screen payload) or the default thin outline treeLine for the Task List:
Migration notes
?view=fullkeeps v1's top-level keys and per-node shape, minusinitial_user_clipboard. Read the clipboard from/api/content-staging/v1/clipboard/.children_url.?format=concisehas no equivalent; v1's concise form also listed the components inside units.How it is marked:
deprecated: truein the CMS schema, plus a docstring note on the v1 view. No response header.Window: this ticket's own schedule. The marking ships in the next named release after Verawood, and the deprecated address is removed one named release after that.
Abdul-Muqadim-Arbisoft commentedon Oct 15, 2026
Entry for this ticket: user API directory listings (users, user preferences, time zones). The replacement is in review in #39297, which now carries the work first opened as #39237 (closed unmerged). Please add the lines below when it merges.
Rows for the Description table:
GET /api/user/v1/users/GET /api/user/v2/users/GET /api/user/v1/users/{id}/GET /api/user/v2/users/{username}/GET /api/user/v1/user_prefs/GET /api/user/v2/user_preferences/GET /api/user/v1/user_prefs/{id}/GET /api/user/v2/user_preferences/{username},{key}/GET /api/user/v1/preferences/{pref_key}/users/GET /api/user/v2/users/?preference_key={pref_key}GET /api/user/v1/forum_roles/{name}/users/GET /api/user/v2/users/?forum_role={name}&course_key={course_key}GET /api/user/v1/preferences/time_zones/GET /api/user/v2/time_zones/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.Studio mounts these addresses too and marks them in its
/api-docs/. The replacements are served by the LMS only. The replacements admit the site's API key (X-Edx-Api-Key), as these addresses do, so integrations move without changing their credential.The timeline is this ticket's: removed one named release after the release this ships in.
Faraz32123 commentedon Oct 15, 2026
Withdrawn: contentstore legacy library list. #39238 was closed without merging. Legacy libraries are deprecated in #37931 and their backend is removed after the Xylon cutoff, so no replacement is being added. Please don't add rows or a task-list line for it here; the legacy library list addresses are covered by #37931.
docs: mark the v1 course index deprecated in favour of the v2 outline
docs: mark v1 and v0 course grading deprecated in favour of authoring v3
taimoor-ahmed-1 commentedon Oct 22, 2026
Entry for this ticket: contentstore container handler. The replacement is in review in #39274 (stacked on #39229); please add the lines below when it merges.
Rows for the Description table:
GET /api/contentstore/v1/container_handler/{usage_key_string}GET /api/authoring/v2/containers/{usage_key}/?view=full(the Unit page payload) or the default thin container viewLine for the Task List:
Migration notes
?view=fullkeeps v1's fields and shapes, minususer_clipboardandaction. Read the clipboard from/api/content-staging/v1/clipboard/.view=fullis available for a unit or a container inside a unit. Sections and subsections answer the default view; withview=fullthey answer 404 (v1 answered 500)./api/authoring/v1/xblocks/{usage_key}/for component data. Library andi4x://keys answer 404.How it is marked:
deprecated: truein the CMS schema, plus a docstring note on the v1 view. No response header.Window: this ticket's own schedule. The marking ships in the next named release after Verawood, and the deprecated address is removed one named release after that.
Abdul-Muqadim-Arbisoft commentedon Oct 23, 2026
Entry for this ticket: user account, profile image, ID verification and name-change APIs. The replacement is in review in #39297; please add the lines below when it merges.
Rows for the Description table:
GET /api/user/v1/meGET /api/user/v2/accounts/me/GET /api/user/v1/accountsGET /api/user/v2/accounts/POST /api/user/v1/accounts/search_emailsPOST /api/user/v2/email_searches/GET/PATCH /api/user/v1/accounts/{username}GET/PATCH /api/user/v2/accounts/{username}/POST /api/user/v1/accounts/{username}/deactivate/POST /api/user/v2/accounts/{username}/deactivation/POST/DELETE /api/user/v1/accounts/{username}/imagePOST/DELETE /api/user/v2/accounts/{username}/profile_image/GET /api/user/v1/accounts/{username}/verification_status/GET /api/user/v2/accounts/{username}/verification_status/GET /api/user/v1/accounts/{username}/verifications/GET /api/user/v2/accounts/{username}/verifications/POST /api/user/v1/accounts/name_change/POST /api/user/v2/name_changes/POST /api/user/v1/accounts/name_change/{username}/confirm/POST /api/user/v2/name_changes/{username}/confirmations/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.Both services serve these addresses. Studio mounts the same version 1 user API at
/api/user/, and its/api-docs/marks these operationsdeprecated: truetoo. Every replacement is served by the LMS only. A caller that uses these addresses on the Studio host moves to the LMS's/api/user/v2/addresses. No Studio page calls them.Published bodies. The version 1 search, name change and account change are documented with the request bodies their handlers read:
emailsof any length,nameof any length, and account properties without types. They no longer carry the version 2 bounds. In the LMS's service-wide document, the name-change confirmation and the imagePOSTpublish204, the code their handlers answer, instead of200.The timeline is this ticket's: removed one named release after the release this ships in.
taimoor-ahmed-1 commentedon Oct 25, 2026
Entry for this ticket: contentstore advanced settings. The replacement is in review in #39303; please add the lines below when it merges.
Rows for the Description table:
GET /api/contentstore/v0/advanced_settings/{course_id}GET /api/authoring/v1/courses/{course_key}/advanced_settings/(noview= v0fetch_all=0;view=full= v0 default)PATCH /api/contentstore/v0/advanced_settings/{course_id}PATCH /api/authoring/v1/courses/{course_key}/advanced_settings/Line for the Task List:
Migration notes
fetch_all=0); requestview=fullfor every field (v0's default).filter_fieldsbecomesfields, which selects within the chosen view.fetch_allandfilter_fieldsare ignored on v1.How it is marked:
deprecated: truein the CMS schema. The legacy views are not edited, and there is no response header.Window: this ticket's own schedule. The marking ships in the next named release after Verawood, and the deprecated address is removed one named release after that.
12 remaining items
docs: remove the deprecation note from the v1 group configurations do…
docs: remove the deprecation notes from the v0 course optimizer docst…
docs: remove the deprecation note from the v1 course team docstring
docs: remove the deprecation notes from the v0 advanced settings docs…
docs: remove the deprecation note from the v1 group configurations do…
docs: remove the deprecation notes from the v1 settings and rerun doc…
Abdul-Muqadim-Arbisoft commentedon Nov 1, 2026
Entry for this ticket: user preferences and email opt-in APIs. The replacement is in review in #39314; please add the lines below when it merges.
Rows for the Description table:
GET/PATCH /api/user/v1/preferences/{username}GET/PATCH /api/user/v2/accounts/{username}/preferences/GET/PUT/DELETE /api/user/v1/preferences/{username}/{preference_key}GET/PUT/DELETE /api/user/v2/accounts/{username}/preferences/{key}/POST /api/user/v1/preferences/email_opt_in/POST /api/user/v2/email_opt_ins/POST /user_api/v1/preferences/email_opt_in/POST /api/user/v2/email_opt_ins/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.Removal covers the LMS only. Studio also mounts the version 1 user API at
/api/user/(cms/urls.py) and serves no/api/user/v2/. Its header language selector reads and changes the language through/api/user/v1/preferences/{username}. So Studio's copies of/api/user/v1/preferences/{username},/api/user/v1/preferences/{username}/{preference_key}and/api/user/v1/preferences/email_opt_in/are not marked deprecated in Studio's document. They stay until Studio has a replacement on its own host.One row is marked nowhere, and is listed here for that reason. The fourth,
POST /user_api/v1/preferences/email_opt_in/, is the same view as the third at a second, unversioned address. It keeps resolving and carries no schema mark, because marking it would admit an unversioned path into the published document — which is how the other/user_api/v1/twins are treated too. It is listed so that it is removed alongside its sibling rather than left behind; this ticket is the only deprecation signal its callers get.What the published document says about two of these operations changes, and what they answer does not. In the LMS's service-wide document,
PATCH /api/user/v1/preferences/{username}andPUT /api/user/v1/preferences/{username}/{preference_key}now publish204, which both handlers have always answered, instead of200. Both now also publish the request body their handler reads: the change is an object naming at least one preference, and the values carry no type, because both handlers store the text of any value. The handlers, their service and their URLconfs are not in the diff.The timeline is this ticket's: removed one named release after the release this ships in.
Abdul-Muqadim-Arbisoft commentedon Nov 1, 2026
Entry for this ticket: registration, sign-in, password reset and registration validation. The replacement is in review in #39331; please add the lines below when it merges.
Rows for the Description table:
GET /api/user/v1/account/registration/GET /api/user/v2/registrations/(answers as version 2: a configuredconfirm_emailfield is listed in the form)POST /api/user/v1/account/registration/POST /api/user/v2/registrations/(answers as version 2: a configured requiredconfirm_emailis enforced)GET /api/user/v2/account/registration/GET /api/user/v2/registrations/POST /api/user/v2/account/registration/POST /api/user/v2/registrations/GET /api/user/v1/account/password_reset/GET /api/user/v2/password_resets/POST /api/user/v1/account/password_reset/token/validate/POST /api/user/v2/password_reset_token_validations/POST /api/user/v1/validation/registrationPOST /api/user/v2/registration_validations/(the address now ends in a slash)GET /api/user/{api_version}/account/login_session/(v1 and v2)GET /api/user/v2/login_sessions/POST /api/user/{api_version}/account/login_session/(v1 and v2)POST /api/user/v2/login_sessions/(a version 1 caller also sendsemail_or_usernamein place ofemail)Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema: the LMS's/lms-api/schema/document and the service-wide/api-docs/documents of the LMS and of Studio. Of this ticket's step-1 markers only the schema flag is applied: noWarningresponse header and no separate docs page. The replacement addresses are served by the LMS only. Studio's document marks the same nine operations because Studio serves them, but Studio mounts none of the replacements.Not covered by this entry: the unversioned twins of these routes, which keep resolving and are not marked:
/user_api/v1/account/registration/,/user_api/v2/account/registration/,/user_api/{api_version}/account/login_session/,/user_api/v1/account/password_reset/and/user_api/v1/account/password_reset/token/validate/, and also/create_account. The/user_api/v1/twins of the addresses entered on this ticket earlier are not marked either; deprecating the twins is one decision for all of them at once.Removal prerequisites, to be met before the rows above are removed:
ENABLE_AUTHN_MICROFRONTENDis off, which is its default. That page posts to thesubmit_urlof the sign-in form description, which names the version 1 sign-in address and the version 1 fieldemail. The form description has to namePOST /api/user/v2/login_sessions/and the fieldemail_or_username; until it does, the version 1 arm of the templated sign-in address cannot be removed.submit_urlnames/api/user/v2/account/registration/for every request that is not version 1, including requests answered at/api/user/v2/registrations/. It has to name/api/user/v2/registrations/before the version 2 registration address can be removed.POST /api/user/v1/account/registration/, and the authentication front end posts the version 2 registration and sign-in addresses andPOST /api/user/v1/validation/registration.Superseded views: The superseded views are left untouched: no response header and no deprecation notes in code.
The timeline is this ticket's: removed one named release after the release this ships in.
Move edX enrollment calls to the v2 enrollment API with a JWT
Abdul-Muqadim-Arbisoft commentedon Nov 5, 2026
Entry for this ticket: the account retirement pipeline, driver-facing operations. The replacement is in review in #39330; please add the lines below when it merges.
Rows for the Description table:
GET /api/user/v1/accounts/{username}/retirement_status/GET /api/user/v2/retirements/{username}/GET /api/user/v1/accounts/retirement_queue/GET /api/user/v2/retirements/GET /api/user/v1/accounts/retirements_by_status_and_date/GET /api/user/v2/retirements/(the same collection, narrowed by?state=,?created_after=and?created_before=)PATCH /api/user/v1/accounts/update_retirement_status/PATCH /api/user/v2/retirements/{username}/POST /api/user/v1/accounts/cancel_retirement/DELETE /api/user/v2/retirements/{username}/POST /api/user/v1/accounts/retire/POST /api/user/v2/retirements/{username}/erasures/with{"scope": "lms_core"}POST /api/user/v1/accounts/retire_misc/{"scope": "lms_misc"}POST /api/user/v1/accounts/retirement_cleanup/POST /api/user/v2/retirement_cleanups/POST /api/user/v1/accounts/retirement_partner_report/POST /api/user/v2/retirement_partner_reports/PUT /api/user/v1/accounts/retirement_partner_report/PUT /api/user/v2/retirement_partner_reports/{username}/POST /api/user/v1/accounts/retirement_partner_report_cleanup/POST /api/user/v2/retirement_partner_report_cleanups/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded views are left untouched: no response header and no deprecation notes in code.The operator has to act on two things before these are removed.
400(user/ambiguous-account-name) on every conforming operation that resolves a record by name. The superseded member operations act on the first matching record. A driver that relied on being handed one of several records must now distinguish them.DELETE /api/user/v2/retirement_cleanups/— is answered405withAllow: POST, OPTIONS, where the superseded disposal answered403. The published document already lists the methods each address serves. A caller that holds the capability was answered405on these pairs before and after; an anonymous caller is still401.cool_off_daysabove 36,500) is refused400onGET /api/user/v2/retirements/. The queue read answers it with no rows, or with a server error for a period that reaches back past the first year of the calendar.Batch disposals take the whole queue. As on version 1,
POST /api/user/v2/retirement_cleanups/and…/retirement_partner_report_cleanups/put no limit on how many names one request carries, and they compare each name exactly as sent. The partner-report claim takes every waiting entry unless?limit=(1–100) is sent.Two operations of this area are not on this entry.
POST /api/user/v1/accounts/replace_usernames/andPOST /api/user/v1/accounts/deactivate_logout/keep answering and carry no deprecation mark, because their conforming successors are not mounted yet; they follow in #39334 and get their own entry. A test asserts that both stay unmarked, so neither can be flagged here by accident.The timeline is this ticket's: removed one named release after the release this ships in.
Abdul-Muqadim-Arbisoft commentedon Nov 5, 2026
Entry for this ticket: username replacement and self-service account retirement. The replacement is in review in #39334; please add the lines below when it merges.
Rows for the Description table:
POST /api/user/v1/accounts/replace_usernames/POST /api/user/v2/username_replacements/POST /api/user/v1/accounts/deactivate_logout/POST /api/user/v2/retirements/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema: the LMS's documents through the user API's own post-processing hook, and Studio's/api-docs/, because Studio serves both addresses too and lists them in its own superseded paths. That is the only marker. The superseded views are left untouched, with no response header and no deprecation notes in code. Both addresses keep resolving with the same statuses, bodies, media types and authentication they answer today.Notes for callers:
passwordfield. It also reads that body as JSON, which the superseded address parses and then refuses.deactivate_logout/: that rule has to be changed when the address is.{"username_mappings": [{"stored_name": "name_asked_for"}]}, takes any number of mappings in one request, an empty list included, as the superseded address does, and reports one result per mapping (replaced,no_such_accountorfailed) where the superseded address returns two arrays. A name no account is stored under is reportedno_such_account, where the superseded address lists it as replaced. A name of any shape is written as the superseded address writes it, and a mapping the database refuses is reportedfailedwhile the rest are carried out.The timeline is this ticket's: removed one named release after the release this ships in.
Faraz32123 commentedon Nov 10, 2026
Entry for this ticket: contentstore help URLs. The replacement is in review in #39264; please add the lines below when it merges.
Rows for the Description table:
GET /api/contentstore/v1/help_urlsGET /api/authoring/v2/help_urls/Line for the Task List:
How it is marked:
deprecated: truein the published OpenAPI schema. The superseded view is left untouched: no response header and no deprecation notes in code.The timeline is this ticket's: removed one named release after the release this ships in.
taimoor-ahmed-1 commentedon Nov 10, 2026
Entry for this ticket: LMS cohorts. The replacement is in review in #39140; please add the lines below when it merges.
Rows for the Description table:
GET/PUT /api/cohorts/v1/settings/{course_id}GET/PUT /api/cohorts/v2/courses/{course_key}/cohort_settings/GET/POST /api/cohorts/v1/courses/{course_id}/cohortsGET/POST /api/cohorts/v2/courses/{course_key}/cohorts/GET/PATCH /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}GET/PATCH /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/GET/POST /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/usersGET/POST /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/users/DELETE /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users/{username}DELETE /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/users/{username}/POST /api/cohorts/v1/courses/{course_id}/users(CSV upload) has no v2 successor and is not deprecated by #39140.Line for the Task List:
Migration notes
count/next/previous/resultsenvelope; v1 returned the first page as a bare array.?ordering=takesname,-name,idor-id; v1 tookasc/descand always sorted by name.PUTor a v1 read has created the rows.unknown,invalid,not_allowed), not as a request-level error.How it is marked:
deprecated: truein the LMS schema, plus a docstring note on the three v1 views. No response header.Window: this ticket's own schedule. The marking ships in the next named release after Verawood, and the deprecated addresses are removed one named release after that.
fix: report assignments a plugin refuses, and record the v1 removal w…
docs: mark v1 and v0 course grading deprecated in favour of authoring v3