Skip to content

[DEPR]: Contentstore and enrollment API versions superseded by FC-0118 #39128

Open

Description

@Faraz32123

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 APIView to ViewSet + 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.

  1. Now — endpoints marked deprecated: deprecated: true in the OpenAPI
    schema, a Warning response header, and docs pointing at the replacements.
  2. Next named release — both versions ship; the deprecated ones still work.
  3. 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

Activity

  1. added
    deprProposal for deprecation & removal per OEP-21
    on Sep 18, 2026
  2. Abdul-Muqadim-Arbisoft commented on Sep 27, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    POST /api/contentstore/v0/videos/uploads/{course_id} POST /api/authoring/v1/courses/{course_key}/videos/ #39060
    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) and GET/DELETE /api/authoring/v1/courses/{course_key}/videos/{edx_video_id}/ #39060

    Line for the Task List:

    How it is marked: deprecated: true in 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.

  3. Abdul-Muqadim-Arbisoft commented on Oct 4, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/contentstore/v1/videos/{course_id}/{edx_video_id}/usage GET /api/authoring/v2/courses/{course_key}/video_usages/{edx_video_id}/ #39071
    PUT /api/contentstore/v1/videos/{course_id}/download POST /api/authoring/v2/courses/{course_key}/video_archives/ #39071

    Line for the Task List:

    Removal step for this area: move VideoDownloadThrottle out of cms/djangoapps/contentstore/rest_api/v1/views/videos.py before that module is deleted. The v2 archive view and its tests import it from there, so deleting the module first breaks the import of cms/urls.py.

    How it is marked: deprecated: true in 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.

  4. taimoor-ahmed-1 commented on Oct 13, 2026

    @taimoor-ahmed-1
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET/POST /api/contentstore/v1/course_grading/{course_id} GET/PATCH /api/authoring/v3/courses/{course_key}/grading/ #39065
    GET/PATCH /api/contentstore/v3/authoring_grading/{course_key}/ GET/PATCH /api/authoring/v3/courses/{course_key}/grading/ #39065

    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

    • The GET returns the grading policy at the top level instead of under course_details.
    • ?view=full adds course_assignment_lists, default_grade_designations, is_credit_course, show_credit_eligibility and mfe_proctored_exam_settings_url, under the v1 names. grace_period also gains seconds.
    • The v1 POST body is accepted by PATCH with the same keys, but PATCH validates it: cutoff values and minimum_grade_credit must be JSON numbers (a string, including "", is refused with 400), grader type and short_label must be strings and graders a list. v1 and v0 store those bodies as sent. PATCH also accepts partial bodies, changing only the fields sent.
    • Bearer tokens are not accepted: use JWT or a session.
    • Errors use the standardized envelope.
    • The trailing slash is required.
    • Slash-form (Old Mongo) course keys are served only by the deprecated addresses.

    How it is marked: deprecated: true in 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.

  5. taimoor-ahmed-1 commented on Oct 14, 2026

    @taimoor-ahmed-1
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    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 tree #39066

    Line for the Task List:

    Migration notes

    • ?view=full keeps v1's top-level keys and per-node shape, minus initial_user_clipboard. Read the clipboard from /api/content-staging/v1/clipboard/.
    • The default view is a thin tree two levels deep. Nodes cut at the depth limit carry children_url.
    • ?format=concise has no equivalent; v1's concise form also listed the components inside units.
    • Blocks with pre-1900 start dates are reported as stored; v1 repaired them on read.
    • Inactive browser sessions and Bearer tokens are refused; use JWT or an active session.
    • Slash-form course keys are served only by v1.
    • The trailing slash is required.
    • Errors use the standardized envelope.

    How it is marked: deprecated: true in 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.

  6. Abdul-Muqadim-Arbisoft commented on Oct 15, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/user/v1/users/ GET /api/user/v2/users/ #39058
    GET /api/user/v1/users/{id}/ GET /api/user/v2/users/{username}/ #39058
    GET /api/user/v1/user_prefs/ GET /api/user/v2/user_preferences/ #39058
    GET /api/user/v1/user_prefs/{id}/ GET /api/user/v2/user_preferences/{username},{key}/ #39058
    GET /api/user/v1/preferences/{pref_key}/users/ GET /api/user/v2/users/?preference_key={pref_key} #39058
    GET /api/user/v1/forum_roles/{name}/users/ GET /api/user/v2/users/?forum_role={name}&course_key={course_key} #39058
    GET /api/user/v1/preferences/time_zones/ GET /api/user/v2/time_zones/ #39058

    Line for the Task List:

    • user API directory listings (users, user preferences, time zones) — #39297 (#39058)

    How it is marked: deprecated: true in 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.

  7. Faraz32123 commented on Oct 15, 2026

    @Faraz32123
    ContributorAuthor

    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.

  8. taimoor-ahmed-1 commented on Oct 22, 2026

    @taimoor-ahmed-1
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    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 view #39064

    Line for the Task List:

    Migration notes

    • ?view=full keeps v1's fields and shapes, minus user_clipboard and action. Read the clipboard from /api/content-staging/v1/clipboard/.
    • The default view is a thin container representation: id, type, name, unit, position and ancestors.
    • view=full is available for a unit or a container inside a unit. Sections and subsections answer the default view; with view=full they answer 404 (v1 answered 500).
    • A missing block answers 404 (v1: 400 with an empty body). A leaf component key answers 404 (v1: 200); use /api/authoring/v1/xblocks/{usage_key}/ for component data. Library and i4x:// keys answer 404.
    • Inactive browser sessions and Bearer tokens are refused; use JWT or an active session.
    • The trailing slash is required.
    • Errors use the standardized envelope.

    How it is marked: deprecated: true in 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.

  9. Abdul-Muqadim-Arbisoft commented on Oct 23, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/user/v1/me GET /api/user/v2/accounts/me/ #39058
    GET /api/user/v1/accounts GET /api/user/v2/accounts/ #39058
    POST /api/user/v1/accounts/search_emails POST /api/user/v2/email_searches/ #39058
    GET/PATCH /api/user/v1/accounts/{username} GET/PATCH /api/user/v2/accounts/{username}/ #39058
    POST /api/user/v1/accounts/{username}/deactivate/ POST /api/user/v2/accounts/{username}/deactivation/ #39058
    POST/DELETE /api/user/v1/accounts/{username}/image POST/DELETE /api/user/v2/accounts/{username}/profile_image/ #39058
    GET /api/user/v1/accounts/{username}/verification_status/ GET /api/user/v2/accounts/{username}/verification_status/ #39058
    GET /api/user/v1/accounts/{username}/verifications/ GET /api/user/v2/accounts/{username}/verifications/ #39058
    POST /api/user/v1/accounts/name_change/ POST /api/user/v2/name_changes/ #39058
    POST /api/user/v1/accounts/name_change/{username}/confirm/ POST /api/user/v2/name_changes/{username}/confirmations/ #39058

    Line for the Task List:

    • user account, profile image, ID verification and name-change APIs — #39297 (#39058)

    How it is marked: deprecated: true in 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 operations deprecated: true too. 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: emails of any length, name of 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 image POST publish 204, the code their handlers answer, instead of 200.

    The timeline is this ticket's: removed one named release after the release this ships in.

  10. taimoor-ahmed-1 commented on Oct 25, 2026

    @taimoor-ahmed-1
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/contentstore/v0/advanced_settings/{course_id} GET /api/authoring/v1/courses/{course_key}/advanced_settings/ (no view = v0 fetch_all=0; view=full = v0 default) #39059
    PATCH /api/contentstore/v0/advanced_settings/{course_id} PATCH /api/authoring/v1/courses/{course_key}/advanced_settings/ #39059

    Line for the Task List:

    Migration notes

    • The default read is the set of settings course authors edit (v0 with fetch_all=0); request view=full for every field (v0's default).
    • filter_fields becomes fields, which selects within the chosen view. fetch_all and filter_fields are ignored on v1.
    • A refused value is reported under its setting name with a fixed message.
    • Bearer tokens are refused; use JWT or a session.
    • The trailing slash is required.
    • Errors use the standardized envelope.

    How it is marked: deprecated: true in 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.

  11. 12 remaining items

  12. Abdul-Muqadim-Arbisoft commented on Nov 1, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET/PATCH /api/user/v1/preferences/{username} GET/PATCH /api/user/v2/accounts/{username}/preferences/ #39058
    GET/PUT/DELETE /api/user/v1/preferences/{username}/{preference_key} GET/PUT/DELETE /api/user/v2/accounts/{username}/preferences/{key}/ #39058
    POST /api/user/v1/preferences/email_opt_in/ POST /api/user/v2/email_opt_ins/ #39058
    POST /user_api/v1/preferences/email_opt_in/ POST /api/user/v2/email_opt_ins/ #39058

    Line for the Task List:

    • user preferences and email opt-in APIs — #39314 (#39058)

    How it is marked: deprecated: true in 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} and PUT /api/user/v1/preferences/{username}/{preference_key} now publish 204, which both handlers have always answered, instead of 200. 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.

  13. Abdul-Muqadim-Arbisoft commented on Nov 1, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/user/v1/account/registration/ GET /api/user/v2/registrations/ (answers as version 2: a configured confirm_email field is listed in the form) #39058
    POST /api/user/v1/account/registration/ POST /api/user/v2/registrations/ (answers as version 2: a configured required confirm_email is enforced) #39058
    GET /api/user/v2/account/registration/ GET /api/user/v2/registrations/ #39058
    POST /api/user/v2/account/registration/ POST /api/user/v2/registrations/ #39058
    GET /api/user/v1/account/password_reset/ GET /api/user/v2/password_resets/ #39058
    POST /api/user/v1/account/password_reset/token/validate/ POST /api/user/v2/password_reset_token_validations/ #39058
    POST /api/user/v1/validation/registration POST /api/user/v2/registration_validations/ (the address now ends in a slash) #39058
    GET /api/user/{api_version}/account/login_session/ (v1 and v2) GET /api/user/v2/login_sessions/ #39058
    POST /api/user/{api_version}/account/login_session/ (v1 and v2) POST /api/user/v2/login_sessions/ (a version 1 caller also sends email_or_username in place of email) #39058

    Line for the Task List:

    • registration, sign-in, password reset and registration validation — #39331 (#39058)

    How it is marked: deprecated: true in 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: no Warning response 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:

    1. The stock LMS renders its own sign-in page while ENABLE_AUTHN_MICROFRONTEND is off, which is its default. That page posts to the submit_url of the sign-in form description, which names the version 1 sign-in address and the version 1 field email. The form description has to name POST /api/user/v2/login_sessions/ and the field email_or_username; until it does, the version 1 arm of the templated sign-in address cannot be removed.
    2. The registration form description's submit_url names /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.
    3. Known callers to move first: the Android app posts POST /api/user/v1/account/registration/, and the authentication front end posts the version 2 registration and sign-in addresses and POST /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.

  14. Abdul-Muqadim-Arbisoft commented on Nov 5, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/user/v1/accounts/{username}/retirement_status/ GET /api/user/v2/retirements/{username}/ #39058
    GET /api/user/v1/accounts/retirement_queue/ GET /api/user/v2/retirements/ #39058
    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=) #39058
    PATCH /api/user/v1/accounts/update_retirement_status/ PATCH /api/user/v2/retirements/{username}/ #39058
    POST /api/user/v1/accounts/cancel_retirement/ DELETE /api/user/v2/retirements/{username}/ #39058
    POST /api/user/v1/accounts/retire/ POST /api/user/v2/retirements/{username}/erasures/ with {"scope": "lms_core"} #39058
    POST /api/user/v1/accounts/retire_misc/ the same address with {"scope": "lms_misc"} #39058
    POST /api/user/v1/accounts/retirement_cleanup/ POST /api/user/v2/retirement_cleanups/ #39058
    POST /api/user/v1/accounts/retirement_partner_report/ POST /api/user/v2/retirement_partner_reports/ #39058
    PUT /api/user/v1/accounts/retirement_partner_report/ PUT /api/user/v2/retirement_partner_reports/{username}/ #39058
    POST /api/user/v1/accounts/retirement_partner_report_cleanup/ POST /api/user/v2/retirement_partner_report_cleanups/ #39058

    Line for the Task List:

    • account retirement pipeline, driver-facing operations — #39330 (#39058)

    How it is marked: deprecated: true in 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.

    1. A Studio caller has no successor. The URL module that carries all eleven superseded addresses is included by Studio as well as by the LMS, so a driver pointed at Studio reaches them today. Every conforming successor is mounted in the LMS only. A deployment whose retirement driver calls Studio must point it at the LMS as part of migrating, not merely rename the addresses. This is the one migration step that is not a rename.
    2. Four answers change at the conforming addresses. Each is deliberate and is described in full in the PR body; they are repeated here because an operator reading this ticket may not read the PR.
      • An account name that more than one retirement record was requested under is refused 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.
      • A write happens on the two conforming queue reads, and it is the platform's own: the language sync stores the caller's language preference on any authenticated request, writing one row on the first such request. The reads themselves change nothing. It is declared because a read that writes anything has to be.
      • An authenticated caller without the pipeline's capability that sends a method no operation is wired to — for example DELETE /api/user/v2/retirement_cleanups/ — is answered 405 with Allow: POST, OPTIONS, where the superseded disposal answered 403. The published document already lists the methods each address serves. A caller that holds the capability was answered 405 on these pairs before and after; an anonymous caller is still 401.
      • A cooling-off period longer than a century (cool_off_days above 36,500) is refused 400 on GET /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/ and POST /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.

  15. Abdul-Muqadim-Arbisoft commented on Nov 5, 2026

    @Abdul-Muqadim-Arbisoft
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    POST /api/user/v1/accounts/replace_usernames/ POST /api/user/v2/username_replacements/ #39058
    POST /api/user/v1/accounts/deactivate_logout/ POST /api/user/v2/retirements/ #39058

    Line for the Task List:

    • username replacement and self-service account retirement — #39334 (#39058)

    How it is marked: deprecated: true in 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:

    • Nothing a caller presents today has to change in order to change address. The replacement of deactivate_logout accepts the same credentials the superseded address accepts — the platform's own token, a browser session, and an OAuth2 access token sent as a bearer token, which is what the official mobile applications send when a deployment configures them that way — and it reads the same form-encoded body carrying a single password field. It also reads that body as JSON, which the superseded address parses and then refuses.
    • The replacement of deactivate_logout is the POST of the retirement collection. The other operations of that collection are pipeline work and keep asking for the capability they already ask for; the POST asks for no capability beyond being signed in, and acts on the calling account alone.
    • It answers 204 with no body, as the superseded address does. Its three refusals — the password did not match, the account is temporarily locked after repeated failures, and account deletion is turned off for this site — are told apart by the error type in the body, where the superseded address answers 403 with an empty body for the first two and no body for the third.
    • An account that already has a retirement record is answered 409, where the superseded address answers 500.
    • For an application that excludes the superseded address from a token-refresh retry by matching the end of the address, note that the replacement does not end in deactivate_logout/: that rule has to be changed when the address is.
    • The replacement of replace_usernames reads the same JSON body, {"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_account or failed) where the superseded address returns two arrays. A name no account is stored under is reported no_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 reported failed while the rest are carried out.

    The timeline is this ticket's: removed one named release after the release this ships in.

  16. Faraz32123 commented on Nov 10, 2026

    @Faraz32123
    ContributorAuthor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET /api/contentstore/v1/help_urls GET /api/authoring/v2/help_urls/ #39067

    Line for the Task List:

    How it is marked: deprecated: true in 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.

  17. taimoor-ahmed-1 commented on Nov 10, 2026

    @taimoor-ahmed-1
    Contributor

    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:

    Deprecated endpoint Replacement Standardization issue
    GET/PUT /api/cohorts/v1/settings/{course_id} GET/PUT /api/cohorts/v2/courses/{course_key}/cohort_settings/ #39056
    GET/POST /api/cohorts/v1/courses/{course_id}/cohorts GET/POST /api/cohorts/v2/courses/{course_key}/cohorts/ #39056
    GET/PATCH /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id} GET/PATCH /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/ #39056
    GET/POST /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users GET/POST /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/users/ #39056
    DELETE /api/cohorts/v1/courses/{course_id}/cohorts/{cohort_id}/users/{username} DELETE /api/cohorts/v2/courses/{course_key}/cohorts/{cohort_id}/users/{username}/ #39056

    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

    • The cohort list is paginated with the standard count/next/previous/results envelope; v1 returned the first page as a bare array.
    • ?ordering= takes name, -name, id or -id; v1 took asc/desc and always sorted by name.
    • Member pages are in id order.
    • Reads write nothing. A course whose automatic cohorts exist only in the course content, with no settings row yet, lists them on v2 only after a settings PUT or a v1 read has created the rows.
    • Discussion moderators, community TAs and forum admins may read the cohort list and detail (GET and HEAD) and are refused with 403 on members and settings; v1 refused them with 404.
    • An unknown user, an invalid identifier and an assignment a plugin refuses are reported per entry in the add-members response (unknown, invalid, not_allowed), not as a request-level error.
    • Errors use the standardized envelope. A course key that does not parse gets the envelope's 404.
    • The trailing slash is required.

    How it is marked: deprecated: true in 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    deprProposal for deprecation & removal per OEP-21

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions