From 67256cdbc8cb5822410276157cf0babcee386e8f Mon Sep 17 00:00:00 2001
From: Muhammad Faraz Maqsood <faraz.maqsood@arbisoft.com>
Date: Sat, 26 Sep 2026 14:55:27 +0500
Subject: [PATCH 1/4] feat: apply FC-0118 ADRs to youtube transcripts APIs

Add a conforming v1 surface for the two YouTube transcript endpoints at
/api/authoring/v1/courses/{course_key}/youtube_transcript_{checks,imports}/.
The import operation becomes a POST because the legacy GET performs four
domain writes. Responses are serializer-produced and errors use the
standardized envelope. The v0 routes are untouched and keep resolving at
all four of their live spellings; they are marked deprecated in the schema.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../rest_api/v1/authoring_urls.py             |  23 +
 .../rest_api/v1/serializers/__init__.py       |   6 +
 .../v1/serializers/youtube_transcripts.py     | 114 +++
 .../rest_api/v1/views/__init__.py             |   4 +
 .../views/tests/test_youtube_transcripts.py   | 807 ++++++++++++++++++
 .../rest_api/v1/views/youtube_transcripts.py  | 175 ++++
 .../v1/youtube_transcripts_service.py         | 130 +++
 cms/envs/devstack.py                          |  13 +-
 cms/envs/production.py                        |  13 +-
 cms/lib/spectacular.py                        |  24 +-
 cms/lib/tests/__init__.py                     |   0
 cms/lib/tests/test_spectacular.py             | 120 +++
 cms/urls.py                                   |  11 +
 13 files changed, 1431 insertions(+), 9 deletions(-)
 create mode 100644 cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py
 create mode 100644 cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
 create mode 100644 cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
 create mode 100644 cms/djangoapps/contentstore/rest_api/v1/views/youtube_transcripts.py
 create mode 100644 cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
 create mode 100644 cms/lib/tests/__init__.py
 create mode 100644 cms/lib/tests/test_spectacular.py

diff --git a/cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py b/cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py
new file mode 100644
index 000000000000..abc46e8f8d74
--- /dev/null
+++ b/cms/djangoapps/contentstore/rest_api/v1/authoring_urls.py
@@ -0,0 +1,23 @@
+"""Contentstore API v1 authoring URLs."""
+
+from django.urls import path
+
+from cms.djangoapps.contentstore.rest_api.v1.views import (
+    YoutubeTranscriptChecksViewSet,
+    YoutubeTranscriptImportsViewSet,
+)
+
+app_name = "authoring_v1"
+
+urlpatterns = [
+    path(
+        "courses/<course_key:course_key>/youtube_transcript_checks/",
+        YoutubeTranscriptChecksViewSet.as_view({"get": "list"}),
+        name="youtube_transcript_check_list",
+    ),
+    path(
+        "courses/<course_key:course_key>/youtube_transcript_imports/",
+        YoutubeTranscriptImportsViewSet.as_view({"post": "create"}),
+        name="youtube_transcript_import_list",
+    ),
+]
diff --git a/cms/djangoapps/contentstore/rest_api/v1/serializers/__init__.py b/cms/djangoapps/contentstore/rest_api/v1/serializers/__init__.py
index 26403f734775..d97ea430a096 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/serializers/__init__.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/serializers/__init__.py
@@ -26,3 +26,9 @@
     VideoUploadSerializer,  # noqa: F401
     VideoUsageSerializer,  # noqa: F401
 )
+from .youtube_transcripts import (
+    YoutubeTranscriptCheckRequestSerializer,  # noqa: F401
+    YoutubeTranscriptCheckResultSerializer,  # noqa: F401
+    YoutubeTranscriptImportRequestSerializer,  # noqa: F401
+    YoutubeTranscriptImportResultSerializer,  # noqa: F401
+)
diff --git a/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
new file mode 100644
index 000000000000..b5299f490692
--- /dev/null
+++ b/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
@@ -0,0 +1,114 @@
+"""API Serializers for YouTube transcripts."""
+
+from rest_framework import serializers
+
+
+class YoutubeTranscriptVideoSerializer(serializers.Serializer):
+    """One entry of the video list identifying a source to inspect or import from."""
+
+    type = serializers.CharField(
+        help_text=(
+            'Source kind. "youtube" names a YouTube video id, "edx_video_id" names a '
+            "video in the video pipeline, and any other value is treated as an HTML5 source."
+        ),
+    )
+    video = serializers.CharField(
+        help_text="Identifier of the source, interpreted according to the type field.",
+    )
+    mode = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        help_text='Playback mode of an HTML5 source, such as "mp4" or "webm".',
+    )
+
+    class Meta:
+        ref_name = "YoutubeTranscriptVideo"
+
+
+class YoutubeTranscriptCheckRequestSerializer(serializers.Serializer):
+    """Input identifying the video block whose transcript state is requested."""
+
+    locator = serializers.CharField(
+        help_text="Usage key of the video block to inspect.",
+    )
+    videos = YoutubeTranscriptVideoSerializer(
+        many=True,
+        help_text="Video sources declared on the block, used to decide which transcripts to compare.",
+    )
+
+    class Meta:
+        ref_name = "YoutubeTranscriptCheckRequest"
+
+
+class YoutubeTranscriptImportRequestSerializer(serializers.Serializer):
+    """Input identifying the video block to import a YouTube transcript into."""
+
+    locator = serializers.CharField(
+        help_text="Usage key of the video block to import the transcript into.",
+    )
+    videos = YoutubeTranscriptVideoSerializer(
+        many=True,
+        help_text='Video sources declared on the block. An entry of type "youtube" is required.',
+    )
+
+    class Meta:
+        ref_name = "YoutubeTranscriptImportRequest"
+
+
+class YoutubeTranscriptCheckResultSerializer(serializers.Serializer):
+    """Transcript availability of one video block, across its declared sources."""
+
+    html5_local = serializers.ListField(
+        child=serializers.CharField(),
+        help_text="Identifiers of the HTML5 sources that already have a transcript stored for this course.",
+    )
+    html5_equal = serializers.BooleanField(
+        help_text="Whether exactly two HTML5 sources were found and their stored transcripts are identical.",
+    )
+    is_youtube_mode = serializers.BooleanField(
+        help_text="Whether the block declares a YouTube source, which takes priority over HTML5 sources.",
+    )
+    youtube_local = serializers.BooleanField(
+        help_text="Whether a transcript for the YouTube source is already stored for this course.",
+    )
+    youtube_server = serializers.BooleanField(
+        help_text="Whether YouTube is currently serving a transcript for the video.",
+    )
+    youtube_diff = serializers.BooleanField(
+        help_text="Whether the transcript on YouTube differs from the stored one.",
+    )
+    current_item_subs = serializers.CharField(
+        required=False,
+        allow_null=True,
+        help_text="Name of the transcript currently attached to the block, or null when none is attached.",
+    )
+    status = serializers.CharField(
+        help_text='Outcome of the check: "Success" when the block could be inspected.',
+    )
+    command = serializers.CharField(
+        help_text=(
+            "Action the caller should take next: replace, found, import, choose, "
+            "use_existing, or not_found."
+        ),
+    )
+
+    class Meta:
+        ref_name = "YoutubeTranscriptCheckResult"
+
+
+class YoutubeTranscriptImportResultSerializer(serializers.Serializer):
+    """Outcome of importing a YouTube transcript into a video block."""
+
+    edx_video_id = serializers.CharField(
+        allow_null=True,
+        help_text=(
+            "Video pipeline identifier the transcript was attached to. Null when the block "
+            "lives in a content library, where transcripts are stored on the block itself."
+        ),
+    )
+    status = serializers.CharField(
+        help_text='Outcome of the import: "Success" when the transcript was stored.',
+    )
+
+    class Meta:
+        ref_name = "YoutubeTranscriptImportResult"
diff --git a/cms/djangoapps/contentstore/rest_api/v1/views/__init__.py b/cms/djangoapps/contentstore/rest_api/v1/views/__init__.py
index b413f6705c64..6b3c50cdf31f 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/views/__init__.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/views/__init__.py
@@ -17,3 +17,7 @@
 from .vertical_block import ContainerHandlerView, vertical_container_children_redirect_view  # noqa: F401
 from .videos import CourseVideosView, VideoDownloadView, VideoUsageView  # noqa: F401
 from .xblock import XblockViewSet  # noqa: F401
+from .youtube_transcripts import (
+    YoutubeTranscriptChecksViewSet,  # noqa: F401
+    YoutubeTranscriptImportsViewSet,  # noqa: F401
+)
diff --git a/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
new file mode 100644
index 000000000000..2ce36990b072
--- /dev/null
+++ b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
@@ -0,0 +1,807 @@
+"""Tests for the v1 YouTube transcript endpoints."""
+
+import json
+from unittest.mock import Mock, patch
+
+import ddt
+from django.urls import Resolver404, resolve, reverse
+from edx_rest_framework_extensions.testing import assert_error_envelope
+from edxval.api import create_video
+from opaque_keys.edx.keys import UsageKey
+from organizations.tests.factories import OrganizationFactory
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from cms.djangoapps.contentstore.rest_api.v0.views.transcripts import (
+    YoutubeTranscriptCheckView,
+    YoutubeTranscriptUploadView,
+)
+from cms.djangoapps.contentstore.tests.utils import CourseTestCase
+from common.djangoapps.student.tests.factories import GlobalStaffFactory, InstructorFactory, UserFactory
+from openedx.core.djangoapps.content_libraries import api as lib_api
+from openedx.core.djangoapps.video_config.transcripts_utils import Transcript
+from xmodule.modulestore.django import modulestore
+from xmodule.modulestore.tests.factories import CourseFactory
+from xmodule.video_block import VideoBlock
+
+SRT_TRANSCRIPT_CONTENT = """0
+00:00:10,500 --> 00:00:13,000
+Elephant's Dream
+
+1
+00:00:15,000 --> 00:00:18,000
+At the left we can see...
+
+"""
+
+SJSON_TRANSCRIPT_CONTENT = Transcript.convert(
+    SRT_TRANSCRIPT_CONTENT,
+    Transcript.SRT,
+    Transcript.SJSON,
+)
+
+DOWNLOAD_PATH = "cms.djangoapps.contentstore.views.transcripts_ajax.download_youtube_subs"
+GET_ITEM_PATH = "cms.djangoapps.contentstore.views.transcripts_ajax._get_item"
+
+CHECK_URL_NAME = "authoring_v1:youtube_transcript_check_list"
+IMPORT_URL_NAME = "authoring_v1:youtube_transcript_import_list"
+LEGACY_CHECK_URL_NAME = "cms.djangoapps.contentstore:v0:cms_api_youtube_transcripts_check"
+LEGACY_IMPORT_URL_NAME = "cms.djangoapps.contentstore:v0:cms_api_youtube_transcripts_upload"
+
+YOUTUBE_ID = "test_yt_id"
+
+
+class BaseYoutubeTranscriptTest(CourseTestCase):
+    """Fixtures shared by every YouTube transcript endpoint test."""
+
+    def setUp(self):
+        super().setUp()
+        self.api_client = APIClient()
+        self.password = "password"
+
+        self.video_usage_key = self._create_video_block(self.course)
+        self.item = modulestore().get_item(self.video_usage_key)
+        self._set_fields_from_xml(self.item, '<video youtube="1.0:hI10vDNYz4M" />')
+        modulestore().update_item(self.item, self.user.id)
+        self.item = modulestore().get_item(self.video_usage_key)
+
+        create_video({
+            "edx_video_id": "123-456-789",
+            "status": "upload",
+            "client_video_id": "Test Video",
+            "duration": 0,
+            "encoded_videos": [],
+            "courses": [str(self.course.id)],
+        })
+
+        self.other_course = CourseFactory.create(org="edX", course="OtherX", run="Other_Run")
+
+        self.student = UserFactory.create(username="student", password=self.password)
+        self.global_staff = GlobalStaffFactory(username="global-staff", password=self.password)
+        self.course_instructor = InstructorFactory(
+            username="instructor", password=self.password, course_key=self.course.id,
+        )
+        self.other_course_instructor = InstructorFactory(
+            username="other-course-instructor",
+            password=self.password,
+            course_key=self.other_course.id,
+        )
+
+    def _create_video_block(self, course, category="video"):
+        """Create a block of ``category`` under ``course`` and return its usage key."""
+        response = self.client.ajax_post("/xblock/", {
+            "parent_locator": str(course.location),
+            "category": category,
+            "type": category,
+        })
+        assert response.status_code == status.HTTP_200_OK
+        return UsageKey.from_string(json.loads(response.content.decode("utf-8"))["locator"])
+
+    @staticmethod
+    def _set_fields_from_xml(item, xml):
+        """Apply the field values described by ``xml`` to ``item``."""
+        for key, value in VideoBlock.parse_video_xml(xml).items():
+            setattr(item, key, value)
+
+    def check_url(self, course_key=None):
+        """Return the conforming check address for ``course_key``."""
+        return reverse(CHECK_URL_NAME, kwargs={"course_key": str(course_key or self.course.id)})
+
+    def import_url(self, course_key=None):
+        """Return the conforming import address for ``course_key``."""
+        return reverse(IMPORT_URL_NAME, kwargs={"course_key": str(course_key or self.course.id)})
+
+    def payload(self, locator=None, youtube_id=YOUTUBE_ID, videos=None):
+        """Return a request payload naming ``locator`` and its YouTube source."""
+        body = {"locator": str(locator if locator is not None else self.video_usage_key)}
+        if videos is not None:
+            body["videos"] = videos
+        else:
+            body["videos"] = [{"type": "youtube", "video": youtube_id, "mode": "youtube"}]
+        return body
+
+    def get_check(self, user=None, course_key=None, payload=None):
+        """Call the check endpoint as ``user``."""
+        if user is not None:
+            self.api_client.force_authenticate(user=user)
+        body = self.payload() if payload is None else payload
+        return self.api_client.get(self.check_url(course_key), {"data": json.dumps(body)})
+
+    def post_import(self, user=None, course_key=None, payload=None):
+        """Call the import endpoint as ``user``."""
+        if user is not None:
+            self.api_client.force_authenticate(user=user)
+        body = self.payload() if payload is None else payload
+        return self.api_client.post(self.import_url(course_key), body, format="json")
+
+
+@ddt.ddt
+class TestYoutubeTranscriptChecksAuthorization(BaseYoutubeTranscriptTest):
+    """Allow and deny paths of the check endpoint."""
+
+    def test_anonymous_is_refused(self):
+        response = self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())})
+        assert_error_envelope(response, expected_status=401, expected_type_slug="authn")
+
+    def test_student_is_refused(self):
+        response = self.get_check(user=self.student)
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_instructor_in_another_course_is_refused(self):
+        response = self.get_check(user=self.other_course_instructor)
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_course_instructor_is_allowed(self):
+        response = self.get_check(user=self.course_instructor)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json()["status"] == "Success"
+
+    def test_global_staff_is_allowed(self):
+        response = self.get_check(user=self.global_staff)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json()["status"] == "Success"
+
+
+@ddt.ddt
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptImportsAuthorization(BaseYoutubeTranscriptTest):
+    """Allow and deny paths of the import endpoint."""
+
+    def test_anonymous_is_refused(self):
+        response = self.api_client.post(self.import_url(), self.payload(), format="json")
+        assert_error_envelope(response, expected_status=401, expected_type_slug="authn")
+
+    def test_student_is_refused(self):
+        response = self.post_import(user=self.student)
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_instructor_in_another_course_is_refused(self):
+        response = self.post_import(user=self.other_course_instructor)
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_course_instructor_is_allowed(self):
+        response = self.post_import(user=self.course_instructor)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json()["status"] == "Success"
+
+    def test_global_staff_is_allowed(self):
+        response = self.post_import(user=self.global_staff)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json()["status"] == "Success"
+
+
+@ddt.ddt
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptAuthorizationLayers(BaseYoutubeTranscriptTest):
+    """The per-item checks that survive behind the course-level permission class."""
+
+    def test_check_refuses_locator_pointing_into_another_course(self):
+        """A caller authorized on the URL course cannot reach a block in another course."""
+        other_video = self._create_video_block(self.other_course)
+        response = self.get_check(
+            user=self.course_instructor, payload=self.payload(locator=other_video),
+        )
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_import_refuses_locator_pointing_into_another_course(self):
+        """The same cross-course refusal applies to the write endpoint."""
+        other_video = self._create_video_block(self.other_course)
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator=other_video),
+        )
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    @ddt.data("student", "other_course_instructor")
+    def test_check_refuses_before_the_item_is_loaded(self, actor):
+        """A caller with no rights on the URL course never reaches the item lookup."""
+        with patch(GET_ITEM_PATH) as mocked_get_item:
+            response = self.get_check(user=getattr(self, actor))
+        assert response.status_code == status.HTTP_403_FORBIDDEN
+        assert not mocked_get_item.called
+
+    @ddt.data("student", "other_course_instructor")
+    def test_import_refuses_before_the_item_is_loaded(self, actor):
+        """The write endpoint refuses on the URL course before touching the block."""
+        with patch(GET_ITEM_PATH) as mocked_get_item:
+            response = self.post_import(user=getattr(self, actor))
+        assert response.status_code == status.HTTP_403_FORBIDDEN
+        assert not mocked_get_item.called
+
+    def test_import_refuses_a_library_block_without_edit_rights(self):
+        """The content-library branch refuses a caller who cannot edit the block."""
+        library = lib_api.create_library(
+            org=OrganizationFactory.create(short_name="denyorg"), slug="denylib", title="Deny",
+        )
+        block = lib_api.create_library_block(library.key, "video", "video-denied")
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator=block.usage_key),
+        )
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+    def test_import_allows_a_library_block_with_edit_rights(self):
+        """The content-library branch admits a caller who can edit the block, with a null id."""
+        library = lib_api.create_library(
+            org=OrganizationFactory.create(short_name="alloworg"), slug="allowlib", title="Allow",
+        )
+        block = lib_api.create_library_block(library.key, "video", "video-allowed")
+        response = self.post_import(
+            user=self.user, payload=self.payload(locator=block.usage_key),
+        )
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"edx_video_id": None, "status": "Success"}
+
+
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptWriteBehaviour(BaseYoutubeTranscriptTest):
+    """Which operation writes, and which does not."""
+
+    @staticmethod
+    def _writes(captured):
+        """
+        Return the write statements among ``captured`` queries.
+
+        The authorization engine's cache-invalidation marker is a process-wide
+        singleton row created on first use, not state this endpoint owns, so it
+        is excluded.
+        """
+        return [
+            q["sql"] for q in captured
+            if q["sql"]
+            and q["sql"].lstrip().upper().startswith(("INSERT", "UPDATE", "DELETE"))
+            and "openedx_authz_policycachecontrol" not in q["sql"]
+        ]
+
+    def _capture(self, call):
+        """Run ``call`` and return its response with the queries it issued."""
+        from django.db import connection  # noqa: PLC0415
+        from django.test.utils import CaptureQueriesContext  # noqa: PLC0415
+
+        with CaptureQueriesContext(connection) as captured:
+            response = call()
+        return response, captured.captured_queries
+
+    def test_check_performs_no_domain_writes(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response, queries = self._capture(
+            lambda: self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())}),
+        )
+        assert response.status_code == status.HTTP_200_OK
+        assert self._writes(queries) == []
+
+    def test_repeated_checks_issue_no_writes_at_all(self):
+        """Once the shared caches are warm, the read issues no write of any kind."""
+        self.api_client.force_authenticate(user=self.course_instructor)
+        self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())})
+        response, queries = self._capture(
+            lambda: self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())}),
+        )
+        assert response.status_code == status.HTTP_200_OK
+        writes = [
+            q["sql"] for q in queries
+            if q["sql"] and q["sql"].lstrip().upper().startswith(("INSERT", "UPDATE", "DELETE"))
+        ]
+        assert writes == []
+
+    def test_head_on_check_performs_no_domain_writes(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response, queries = self._capture(
+            lambda: self.api_client.head(self.check_url(), {"data": json.dumps(self.payload())}),
+        )
+        assert response.status_code == status.HTTP_200_OK
+        assert self._writes(queries) == []
+
+    def test_import_creates_an_external_video_for_an_unlinked_block(self):
+        """The write the legacy GET performed still happens, now on the POST."""
+        self.item.edx_video_id = ""
+        modulestore().update_item(self.item, self.user.id)
+
+        response = self.post_import(user=self.course_instructor)
+
+        assert response.status_code == status.HTTP_200_OK
+        created_id = response.json()["edx_video_id"]
+        assert created_id
+        assert modulestore().get_item(self.video_usage_key).edx_video_id == created_id
+
+    def test_import_keeps_an_existing_video_id(self):
+        self.item.edx_video_id = "123-456-789"
+        modulestore().update_item(self.item, self.user.id)
+
+        response = self.post_import(user=self.course_instructor)
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"edx_video_id": "123-456-789", "status": "Success"}
+
+    def test_import_is_not_reachable_by_get(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response = self.api_client.get(self.import_url())
+        assert_error_envelope(
+            response, expected_status=405, expected_type_slug="method-not-allowed",
+        )
+
+    def test_check_is_not_reachable_by_post(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response = self.api_client.post(self.check_url(), self.payload(), format="json")
+        assert_error_envelope(
+            response, expected_status=405, expected_type_slug="method-not-allowed",
+        )
+
+
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptErrors(BaseYoutubeTranscriptTest):
+    """Every error the endpoints can produce, in the standardized envelope."""
+
+    def test_check_rejects_an_absent_data_parameter(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response = self.api_client.get(self.check_url())
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"data": ["Must be a JSON object."]}
+
+    def test_check_rejects_a_non_object_data_parameter(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response = self.api_client.get(self.check_url(), {"data": "[1, 2]"})
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"data": ["Must be a JSON object."]}
+
+    def test_check_rejects_a_payload_without_a_locator(self):
+        response = self.get_check(
+            user=self.course_instructor, payload={"videos": []},
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"locator": ["This field is required."]}
+
+    def test_import_rejects_a_payload_without_a_locator(self):
+        response = self.post_import(user=self.course_instructor, payload={"videos": []})
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"locator": ["This field is required."]}
+
+    def test_import_rejects_a_payload_without_videos(self):
+        response = self.post_import(
+            user=self.course_instructor, payload={"locator": str(self.video_usage_key)},
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"videos": ["This field is required."]}
+
+    def test_check_reports_an_unparseable_locator_as_a_rejected_request(self):
+        response = self.get_check(
+            user=self.course_instructor, payload=self.payload(locator="not-a-usage-key"),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {
+            "locator": ["The transcript status for this video could not be determined."],
+        }
+
+    def test_check_reports_a_missing_block_as_a_rejected_request(self):
+        missing = str(self.course.id.make_usage_key("video", "no-such-block"))
+        response = self.get_check(
+            user=self.course_instructor, payload=self.payload(locator=missing),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+
+    def test_import_reports_a_missing_block_as_a_rejected_request(self):
+        missing = str(self.course.id.make_usage_key("video", "no-such-block"))
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator=missing),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {
+            "locator": ["The YouTube transcript could not be imported for this video."],
+        }
+
+    def test_a_block_outside_a_course_or_library_is_reported_as_not_found(self):
+        """The service translates the handler's own Django-native errors."""
+        from django.http import Http404  # noqa: PLC0415
+        with patch(GET_ITEM_PATH, side_effect=Http404()):
+            response = self.post_import(user=self.course_instructor)
+        assert_error_envelope(response, expected_status=404, expected_type_slug="not-found")
+        assert response.json()["detail"] == "No video block matches the supplied locator."
+
+    def test_import_reports_an_unparseable_locator_as_a_rejected_request(self):
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator="not-a-usage-key"),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+
+    def test_import_reports_a_non_video_block_as_a_rejected_request(self):
+        problem = self._create_video_block(self.course, category="problem")
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator=problem),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+
+    def test_import_without_a_youtube_source_is_rejected(self):
+        response = self.post_import(
+            user=self.course_instructor,
+            payload=self.payload(videos=[{"type": "html5", "video": "v1", "mode": "mp4"}]),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+
+    def test_a_youtube_download_failure_does_not_leak_its_message(self):
+        from openedx.core.djangoapps.video_config.transcripts_utils import (  # noqa: PLC0415
+            GetTranscriptsFromYouTubeException,
+        )
+        secret = "internal youtube client detail 0xDEADBEEF"
+        with patch(DOWNLOAD_PATH, side_effect=GetTranscriptsFromYouTubeException(secret)):
+            response = self.post_import(user=self.course_instructor)
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert secret not in response.content.decode("utf-8")
+
+    def test_an_unknown_course_key_is_refused(self):
+        response = self.get_check(
+            user=self.course_instructor, course_key="course-v1:edX+NoSuch+Course",
+        )
+        assert_error_envelope(response, expected_status=403, expected_type_slug="authz")
+
+
+class TestYoutubeTranscriptUrls(BaseYoutubeTranscriptTest):
+    """The addresses this pass creates, and the ones it must leave alone."""
+
+    def test_conforming_addresses_reverse_to_their_literals(self):
+        course_key = "course-v1:edX+DemoX+Demo"
+        assert reverse(CHECK_URL_NAME, kwargs={"course_key": course_key}) == (
+            f"/api/authoring/v1/courses/{course_key}/youtube_transcript_checks/"
+        )
+        assert reverse(IMPORT_URL_NAME, kwargs={"course_key": course_key}) == (
+            f"/api/authoring/v1/courses/{course_key}/youtube_transcript_imports/"
+        )
+
+    def test_every_live_legacy_spelling_still_resolves_to_its_view(self):
+        base = "/api/contentstore/v0/youtube_transcripts/course-v1:edX+DemoX+Demo"
+        for suffix, view_class in (
+            ("chec", YoutubeTranscriptCheckView),
+            ("check", YoutubeTranscriptCheckView),
+            ("uploa", YoutubeTranscriptUploadView),
+            ("upload", YoutubeTranscriptUploadView),
+        ):
+            match = resolve(f"{base}/{suffix}")
+            assert match.func.cls is view_class
+
+    def test_the_legacy_slashed_addresses_still_do_not_resolve(self):
+        base = "/api/contentstore/v0/youtube_transcripts/course-v1:edX+DemoX+Demo"
+        for suffix in ("check/", "upload/"):
+            try:
+                resolve(f"{base}/{suffix}")
+            except Resolver404:
+                continue
+            raise AssertionError(f"{suffix} resolved but did not before")
+
+    def test_the_legacy_url_names_still_reverse(self):
+        course_id = "course-v1:edX+DemoX+Demo"
+        assert reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": course_id}) == (
+            f"/api/contentstore/v0/youtube_transcripts/{course_id}/chec"
+        )
+        assert reverse(LEGACY_IMPORT_URL_NAME, kwargs={"course_id": course_id}) == (
+            f"/api/contentstore/v0/youtube_transcripts/{course_id}/uploa"
+        )
+
+    def test_the_conforming_url_names_are_unique_in_their_namespace(self):
+        from cms.djangoapps.contentstore.rest_api.v1 import authoring_urls  # noqa: PLC0415
+        names = [pattern.name for pattern in authoring_urls.urlpatterns]
+        assert sorted(names) == ["youtube_transcript_check_list", "youtube_transcript_import_list"]
+
+    def test_a_malformed_course_key_does_not_reach_the_view(self):
+        """An unparseable key fails to route, so no handler runs."""
+        self.api_client.force_authenticate(user=self.course_instructor)
+        with patch(GET_ITEM_PATH) as mocked_get_item:
+            response = self.api_client.get(
+                "/api/authoring/v1/courses/not-a-course-key/youtube_transcript_checks/",
+            )
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+        assert not mocked_get_item.called
+
+    def test_a_deprecated_course_key_does_not_reach_the_view(self):
+        """A pre-opaque-key course id is refused at routing, as for any conforming route."""
+        self.api_client.force_authenticate(user=self.course_instructor)
+        with patch(GET_ITEM_PATH) as mocked_get_item:
+            response = self.api_client.get(
+                "/api/authoring/v1/courses/edX+DemoX+Demo/youtube_transcript_checks/",
+            )
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+        assert not mocked_get_item.called
+
+    def test_a_routing_level_404_is_answered_with_html(self):
+        """
+        A key the converter rejects never enters the view, so the service-wide
+        handler answers it with the Studio error page rather than a JSON body.
+        Pinned so a change to that handler is visible here.
+        """
+        self.api_client.force_authenticate(user=self.course_instructor)
+        response = self.api_client.get(
+            "/api/authoring/v1/courses/not-a-course-key/youtube_transcript_checks/",
+        )
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+        assert response["Content-Type"].startswith("text/html")
+
+    def test_both_surfaces_share_one_domain_implementation(self):
+        """The legacy and conforming addresses reach the same handler functions."""
+        from cms.djangoapps.contentstore.rest_api.v1 import youtube_transcripts_service  # noqa: PLC0415
+        from cms.djangoapps.contentstore.views import transcripts_ajax  # noqa: PLC0415
+
+        assert youtube_transcripts_service.check_transcripts is transcripts_ajax.check_transcripts
+        assert youtube_transcripts_service.replace_transcripts is transcripts_ajax.replace_transcripts
+
+
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptQueryCounts(BaseYoutubeTranscriptTest):
+    """The conforming addresses must not cost more queries than the legacy ones."""
+
+    def _legacy_check(self):
+        self.api_client.force_authenticate(user=self.course_instructor)
+        return self.api_client.get(
+            reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+            {"data": json.dumps(self.payload())},
+        )
+
+    def _count(self, call):
+        """Return the number of queries ``call`` issues, asserting it succeeded."""
+        from django.db import connection  # noqa: PLC0415
+        from django.test.utils import CaptureQueriesContext  # noqa: PLC0415
+
+        with CaptureQueriesContext(connection) as captured:
+            response = call()
+        assert response.status_code == status.HTTP_200_OK
+        return len(captured.captured_queries)
+
+    def test_check_costs_no_more_queries_than_the_legacy_address(self):
+        legacy = self._count(self._legacy_check)
+        conforming = self._count(lambda: self.get_check(user=self.course_instructor))
+        assert conforming <= legacy, f"legacy={legacy} conforming={conforming}"
+
+
+# Differences between the legacy addresses and the conforming ones that the
+# design intends. The parity tests assert these are the only ones, and that
+# each of them actually occurs.
+INTENTIONAL_DIFFERENCES = [
+    ("type", "errors move to the standardized envelope, which the legacy shapes lack"),
+    ("title", "errors move to the standardized envelope, which the legacy shapes lack"),
+    ("status", "the legacy error body carries the message under status; the envelope uses detail"),
+    ("detail", "errors move to the standardized envelope, which the legacy shapes lack"),
+    ("errors", "validation failures name the offending field"),
+    ("html5_equal", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("is_youtube_mode", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("youtube_local", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("youtube_server", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("youtube_diff", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("current_item_subs", "the legacy check error body repeats the whole result dict; the envelope does not"),
+    ("developer_message", "the legacy authorization body carries developer_message; the envelope does not"),
+    ("error_code", "the legacy authorization body carries error_code; the envelope does not"),
+]
+
+VOLATILE_FIELDS = {"instance"}
+
+
+def _normalize(obj, path=""):
+    """Flatten ``obj`` into a ``{json_path: value}`` map, dropping volatile fields."""
+    flat = {}
+    if isinstance(obj, dict):
+        for key in sorted(obj):
+            if key in VOLATILE_FIELDS:
+                continue
+            flat.update(_normalize(obj[key], f"{path}.{key}" if path else key))
+    elif isinstance(obj, list):
+        for index, item in enumerate(obj):
+            flat.update(_normalize(item, f"{path}[{index}]"))
+    else:
+        flat[path] = obj
+    return flat
+
+
+def _changed_paths(legacy, new):
+    """Return the json paths whose value differs between the two bodies."""
+    left, right = _normalize(legacy), _normalize(new)
+    return {
+        key for key in set(left) | set(right)
+        if left.get(key, "<absent>") != right.get(key, "<absent>")
+    }
+
+
+def _unexpected(changed):
+    """Return the changed paths no declared intentional difference covers."""
+    declared = {path for path, _ in INTENTIONAL_DIFFERENCES}
+    return {
+        key for key in changed
+        if not any(key == d or key.startswith(f"{d}.") or key.startswith(f"{d}[") for d in declared)
+    }
+
+
+@patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
+class TestYoutubeTranscriptParity(BaseYoutubeTranscriptTest):
+    """The conforming addresses return what the legacy ones return, bar the declared differences."""
+
+    def setUp(self):
+        super().setUp()
+        self.api_client.force_authenticate(user=self.course_instructor)
+        self.client.login(username=self.course_instructor.username, password=self.password)
+        self.observed_differences = set()
+
+    def legacy_check(self, payload=None):
+        """Call the legacy check address with the session client."""
+        return self.client.get(
+            reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+            {"data": json.dumps(self.payload() if payload is None else payload)},
+        )
+
+    def legacy_import(self, payload=None):
+        """Call the legacy import address with the session client."""
+        return self.client.get(
+            reverse(LEGACY_IMPORT_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+            {"data": json.dumps(self.payload() if payload is None else payload)},
+        )
+
+    def assert_bodies_match(self, legacy, new, expected_status):
+        """Assert the two bodies differ only where the design says they do."""
+        assert legacy.status_code == expected_status, legacy.content
+        assert new.status_code == expected_status, new.content
+        legacy_json = json.loads(legacy.content or b"null")
+        new_json = json.loads(new.content or b"null")
+        changed = _changed_paths(legacy_json, new_json)
+        unexpected = _unexpected(changed)
+        assert not unexpected, (
+            f"undeclared differences {sorted(unexpected)}: legacy={legacy_json} new={new_json}"
+        )
+        self.observed_differences |= changed
+        return legacy_json, new_json
+
+    def test_check_success_body_is_identical(self):
+        legacy_json, new_json = self.assert_bodies_match(
+            self.legacy_check(), self.get_check(), expected_status=200,
+        )
+        assert new_json == legacy_json
+        assert sorted(new_json) == [
+            "command", "current_item_subs", "html5_equal", "html5_local", "is_youtube_mode",
+            "status", "youtube_diff", "youtube_local", "youtube_server",
+        ]
+
+    def test_check_success_passes_a_string_subs_value_through(self):
+        """``current_item_subs`` is a string on the wire, which the new declaration allows."""
+        self.item.sub = "a-subs-name"
+        modulestore().update_item(self.item, self.user.id)
+        legacy_json, new_json = self.assert_bodies_match(
+            self.legacy_check(), self.get_check(), expected_status=200,
+        )
+        assert new_json["current_item_subs"] == legacy_json["current_item_subs"]
+
+    def test_import_success_body_is_identical(self):
+        self.item.edx_video_id = "123-456-789"
+        modulestore().update_item(self.item, self.user.id)
+        legacy_json, new_json = self.assert_bodies_match(
+            self.legacy_import(), self.post_import(), expected_status=200,
+        )
+        assert new_json == legacy_json == {"edx_video_id": "123-456-789", "status": "Success"}
+
+    def test_import_success_for_a_library_block_returns_a_null_video_id(self):
+        """A null id is a success value the legacy serializer would have refused."""
+        library = lib_api.create_library(
+            org=OrganizationFactory.create(short_name="parityorg"), slug="paritylib", title="Parity",
+        )
+        block = lib_api.create_library_block(library.key, "video", "video-parity")
+        self.api_client.force_authenticate(user=self.user)
+        response = self.post_import(payload=self.payload(locator=block.usage_key))
+        assert response.status_code == status.HTTP_200_OK
+        assert response.json() == {"edx_video_id": None, "status": "Success"}
+
+    def test_empty_payload_errors_differ_only_in_the_envelope(self):
+        payload = {"locator": "", "videos": []}
+        legacy, new = self.legacy_check(payload), self.get_check(payload=payload)
+        self.assert_bodies_match(legacy, new, expected_status=400)
+        assert json.loads(new.content)["type"].endswith("/validation")
+
+    def test_bad_locator_errors_differ_only_in_the_envelope(self):
+        payload = self.payload(locator="not-a-usage-key")
+        legacy, new = self.legacy_check(payload), self.get_check(payload=payload)
+        self.assert_bodies_match(legacy, new, expected_status=400)
+
+    def test_non_video_block_errors_differ_only_in_the_envelope(self):
+        payload = self.payload(locator=self._create_video_block(self.course, category="problem"))
+        legacy, new = self.legacy_import(payload), self.post_import(payload=payload)
+        self.assert_bodies_match(legacy, new, expected_status=400)
+
+    def test_missing_youtube_id_errors_differ_only_in_the_envelope(self):
+        payload = self.payload(videos=[{"type": "html5", "video": "v1", "mode": "mp4"}])
+        legacy, new = self.legacy_import(payload), self.post_import(payload=payload)
+        self.assert_bodies_match(legacy, new, expected_status=400)
+
+    def test_unauthenticated_errors_differ_only_in_the_envelope(self):
+        self.client.logout()
+        self.api_client.force_authenticate(user=None)
+        legacy = self.client.get(
+            reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+            {"data": json.dumps(self.payload())},
+        )
+        new = self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())})
+        self.assert_bodies_match(legacy, new, expected_status=401)
+
+    def test_forbidden_errors_differ_only_in_the_envelope(self):
+        self.client.logout()
+        self.client.login(username=self.student.username, password=self.password)
+        self.api_client.force_authenticate(user=self.student)
+        legacy = self.client.get(
+            reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+            {"data": json.dumps(self.payload())},
+        )
+        new = self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())})
+        self.assert_bodies_match(legacy, new, expected_status=403)
+
+    def test_no_shaping_parameter_changes_the_response(self):
+        """Neither ``view`` nor ``fields`` is accepted, so neither alters the body."""
+        default = self.get_check()
+        for parameter in ("view", "fields"):
+            response = self.api_client.get(
+                self.check_url(), {"data": json.dumps(self.payload()), parameter: "minimal"},
+            )
+            assert response.status_code == status.HTTP_200_OK
+            assert response.json() == default.json()
+
+    def test_the_response_is_an_object_not_a_paginated_envelope(self):
+        body = self.get_check().json()
+        assert isinstance(body, dict)
+        assert "results" not in body
+        assert "count" not in body
+
+    def test_every_declared_difference_occurs_somewhere_in_this_suite(self):
+        """No entry may sit in the declared list without a case that produces it."""
+        payload = {"locator": "", "videos": []}
+        self.assert_bodies_match(
+            self.legacy_check(payload), self.get_check(payload=payload), expected_status=400,
+        )
+        import_payload = self.payload(videos=[{"type": "html5", "video": "v1", "mode": "mp4"}])
+        self.assert_bodies_match(
+            self.legacy_import(import_payload),
+            self.post_import(payload=import_payload),
+            expected_status=400,
+        )
+        # A locator the check handler accepts but cannot resolve: the legacy body
+        # repeats the whole result dict, the envelope names the field instead.
+        unresolvable = self.payload(locator="not-a-usage-key")
+        self.assert_bodies_match(
+            self.legacy_check(unresolvable),
+            self.get_check(payload=unresolvable),
+            expected_status=400,
+        )
+        self.client.logout()
+        self.api_client.force_authenticate(user=None)
+        self.assert_bodies_match(
+            self.client.get(
+                reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+                {"data": json.dumps(self.payload())},
+            ),
+            self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())}),
+            expected_status=401,
+        )
+        self.client.login(username=self.student.username, password=self.password)
+        self.api_client.force_authenticate(user=self.student)
+        self.assert_bodies_match(
+            self.client.get(
+                reverse(LEGACY_CHECK_URL_NAME, kwargs={"course_id": str(self.course.id)}),
+                {"data": json.dumps(self.payload())},
+            ),
+            self.api_client.get(self.check_url(), {"data": json.dumps(self.payload())}),
+            expected_status=403,
+        )
+        missing = [
+            path for path, _ in INTENTIONAL_DIFFERENCES
+            if not any(
+                key == path or key.startswith(f"{path}.") or key.startswith(f"{path}[")
+                for key in self.observed_differences
+            )
+        ]
+        assert missing == [], f"declared but never produced: {missing}"
diff --git a/cms/djangoapps/contentstore/rest_api/v1/views/youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/views/youtube_transcripts.py
new file mode 100644
index 000000000000..b315e351e940
--- /dev/null
+++ b/cms/djangoapps/contentstore/rest_api/v1/views/youtube_transcripts.py
@@ -0,0 +1,175 @@
+"""API Views for YouTube transcripts of course videos."""
+
+import json
+
+from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
+from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication
+from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser
+from edx_rest_framework_extensions.errors import ErrorResponseSerializer
+from edx_rest_framework_extensions.mixins import StandardizedErrorMixin
+from rest_framework import viewsets
+from rest_framework.exceptions import ValidationError
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+
+from cms.djangoapps.contentstore.rest_api.v1.serializers import (
+    YoutubeTranscriptCheckRequestSerializer,
+    YoutubeTranscriptCheckResultSerializer,
+    YoutubeTranscriptImportRequestSerializer,
+    YoutubeTranscriptImportResultSerializer,
+)
+from cms.djangoapps.contentstore.rest_api.v1.views.permissions import HasCourseAuthorAccess
+from cms.djangoapps.contentstore.rest_api.v1.youtube_transcripts_service import (
+    get_transcript_check_result,
+    import_transcripts,
+)
+
+_ERROR_RESPONSES = {
+    400: OpenApiResponse(response=ErrorResponseSerializer, description="The request body is invalid."),
+    401: OpenApiResponse(response=ErrorResponseSerializer, description="The requester is not authenticated."),
+    403: OpenApiResponse(
+        response=ErrorResponseSerializer,
+        description="The requester cannot author the course or the addressed video.",
+    ),
+    404: OpenApiResponse(
+        response=ErrorResponseSerializer,
+        description="The course or the addressed video block does not exist.",
+    ),
+}
+
+_DATA_PARAMETER = OpenApiParameter(
+    name="data",
+    description=(
+        "JSON object naming the video to inspect. It carries a `locator` holding the "
+        "usage key of the video block, and a `videos` list of `{type, video, mode}` "
+        "entries describing the block's declared sources."
+    ),
+    required=True,
+    type=str,
+    location=OpenApiParameter.QUERY,
+)
+
+
+class _CourseScopedMixin:
+    """Shared plumbing for the course-scoped YouTube transcript collections."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.course_key = None
+
+    def initial(self, request, *args, **kwargs):
+        """Expose the course key from the path before permission checks run."""
+        self.course_key = kwargs.get("course_key")
+        super().initial(request, *args, **kwargs)
+
+    def get_serializer(self, *args, **kwargs):
+        """Instantiate the response serializer declared on this viewset."""
+        return self.serializer_class(*args, **kwargs)
+
+    @staticmethod
+    def _validated(raw, request_serializer_class):
+        """Return ``raw`` validated against ``request_serializer_class``."""
+        serializer = request_serializer_class(data=raw)
+        serializer.is_valid(raise_exception=True)
+        return serializer.validated_data
+
+    def _payload_from_query(self, request, request_serializer_class):
+        """Return the validated payload carried by the ``data`` query parameter."""
+        raw = request.query_params.get("data", "")
+        try:
+            parsed = json.loads(raw)
+        except ValueError as exc:
+            raise ValidationError({"data": ["Must be a JSON object."]}) from exc
+        if not isinstance(parsed, dict):
+            raise ValidationError({"data": ["Must be a JSON object."]})
+        return self._validated(parsed, request_serializer_class)
+
+    def _payload_from_body(self, request, request_serializer_class):
+        """Return the validated payload carried by the request body."""
+        return self._validated(request.data, request_serializer_class)
+
+
+@extend_schema(tags=["openedx-platform-sdk"])
+class YoutubeTranscriptChecksViewSet(StandardizedErrorMixin, _CourseScopedMixin, viewsets.ViewSet):
+    """
+    Transcript availability reports for the videos of one course.
+
+    A report describes which transcripts already exist for a video block and
+    whether the one published on YouTube differs from the stored one, so a
+    caller can decide whether an import is worth making. Producing a report
+    changes nothing.
+
+    Callable by anyone with authoring rights on both the course in the path and
+    the course the addressed video belongs to.
+    """
+
+    # Studio authors reach this endpoint from the authoring UI while their
+    # account is still inactive, which the default session class rejects.
+    authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser)
+    permission_classes = (IsAuthenticated, HasCourseAuthorAccess)
+    serializer_class = YoutubeTranscriptCheckResultSerializer
+
+    @extend_schema(
+        summary="Report the transcript availability of a video",
+        description=(
+            "Reports which transcripts exist for the video named by the `data` parameter, "
+            "and whether the transcript published on YouTube differs from the stored one."
+        ),
+        parameters=[_DATA_PARAMETER],
+        responses={
+            200: OpenApiResponse(
+                response=YoutubeTranscriptCheckResultSerializer,
+                description="The transcript availability of the requested video.",
+            ),
+            **_ERROR_RESPONSES,
+        },
+    )
+    def list(self, request, course_key):
+        """Return the transcript availability of the requested video."""
+        payload = self._payload_from_query(request, YoutubeTranscriptCheckRequestSerializer)
+        result = get_transcript_check_result(request, payload, course_key)
+        serializer = self.get_serializer(data=result)
+        serializer.is_valid(raise_exception=True)
+        return Response(serializer.validated_data)
+
+
+@extend_schema(tags=["openedx-platform-sdk"])
+class YoutubeTranscriptImportsViewSet(StandardizedErrorMixin, _CourseScopedMixin, viewsets.ViewSet):
+    """
+    Imports of YouTube transcripts into the videos of one course.
+
+    Creating an import downloads the transcript YouTube publishes for a video
+    and stores it against that video, replacing whatever was stored before.
+
+    Callable by anyone with authoring rights on both the course in the path and
+    the course the addressed video belongs to.
+    """
+
+    # Studio authors reach this endpoint from the authoring UI while their
+    # account is still inactive, which the default session class rejects.
+    authentication_classes = (JwtAuthentication, SessionAuthenticationAllowInactiveUser)
+    permission_classes = (IsAuthenticated, HasCourseAuthorAccess)
+    serializer_class = YoutubeTranscriptImportResultSerializer
+
+    @extend_schema(
+        summary="Import a video's transcript from YouTube",
+        description=(
+            "Downloads the transcript YouTube publishes for the video named in the request "
+            "body and stores it against that video, replacing any transcript already stored."
+        ),
+        request=YoutubeTranscriptImportRequestSerializer,
+        responses={
+            200: OpenApiResponse(
+                response=YoutubeTranscriptImportResultSerializer,
+                description="The transcript was downloaded and stored.",
+            ),
+            **_ERROR_RESPONSES,
+        },
+    )
+    def create(self, request, course_key):
+        """Import the video's YouTube transcript and return the resulting record."""
+        payload = self._payload_from_body(request, YoutubeTranscriptImportRequestSerializer)
+        result = import_transcripts(request, payload, course_key)
+        serializer = self.get_serializer(data=result)
+        serializer.is_valid(raise_exception=True)
+        return Response(serializer.validated_data)
diff --git a/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
new file mode 100644
index 000000000000..ae856bf8b056
--- /dev/null
+++ b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
@@ -0,0 +1,130 @@
+"""Service layer for the v1 YouTube transcript endpoints."""
+
+import json
+import logging
+
+from django.core.exceptions import PermissionDenied as DjangoPermissionDenied
+from django.http import Http404, QueryDict
+from edx_rest_framework_extensions.errors import register_error_type
+from rest_framework.exceptions import (
+    APIException,
+    MethodNotAllowed,
+    NotFound,
+    ParseError,
+    PermissionDenied,
+    ValidationError,
+)
+
+from cms.djangoapps.contentstore.views.transcripts_ajax import check_transcripts, replace_transcripts
+from openedx.core.djangoapps.video_config.transcripts_utils import TranscriptsRequestValidationException
+from xmodule.modulestore.exceptions import ItemNotFoundError
+
+log = logging.getLogger(__name__)
+
+# Neither exception is in the library's built-in classification catalog, so
+# without these registrations a wrong verb or an unparseable body would be
+# reported to the client as an internal server error at a 4xx status.
+register_error_type(MethodNotAllowed, "method-not-allowed", "Method Not Allowed")
+register_error_type(ParseError, "parse-error", "Malformed Request")
+
+CHECK_FAILED_MESSAGE = "The transcript status for this video could not be determined."
+IMPORT_FAILED_MESSAGE = "The YouTube transcript could not be imported for this video."
+FORBIDDEN_MESSAGE = "You do not have permission to edit this video."
+NOT_FOUND_MESSAGE = "No video block matches the supplied locator."
+
+
+def _legacy_request(request, payload):
+    """
+    Return the underlying Django request with ``payload`` installed as the
+    ``data`` query parameter the transcript handlers read.
+
+    The handlers accept their input only from the query string. Building the
+    query string here keeps them unmodified while letting the API accept a
+    JSON request body.
+    """
+    django_request = getattr(request, "_request", request)
+    query = QueryDict(mutable=True)
+    query["data"] = json.dumps(payload)
+    django_request.GET = query
+    return django_request
+
+
+def _decode(response):
+    """Return the ``(body, status_code)`` pair of a legacy JSON response."""
+    try:
+        body = json.loads(response.content.decode("utf-8") or "{}")
+    except ValueError:
+        body = {}
+    return body, response.status_code
+
+
+def _translate(exc, course_key, locator, failure_message):
+    """
+    Re-raise a handler exception as its DRF equivalent.
+
+    The handlers raise Django-native exceptions, which the standardized error
+    envelope would otherwise classify as internal server errors. Messages are
+    fixed strings so no internal detail reaches the caller.
+    """
+    if isinstance(exc, DjangoPermissionDenied):
+        log.info(
+            "Denied YouTube transcript access for locator %s under course %s.",
+            locator,
+            course_key,
+        )
+        raise PermissionDenied(FORBIDDEN_MESSAGE) from exc
+    if isinstance(exc, (Http404, ItemNotFoundError)):
+        log.info(
+            "No video block found for locator %s under course %s.",
+            locator,
+            course_key,
+        )
+        raise NotFound(NOT_FOUND_MESSAGE) from exc
+    if isinstance(exc, TranscriptsRequestValidationException):
+        log.warning(
+            "Rejected YouTube transcript request for locator %s under course %s: %s",
+            locator,
+            course_key,
+            exc,
+        )
+        raise ValidationError({"locator": [failure_message]}) from exc
+    raise exc
+
+
+def _run(handler, request, payload, course_key, failure_message):
+    """
+    Call ``handler`` with ``payload`` and return its decoded success body.
+
+    A handler failure becomes a validation error carrying ``failure_message``;
+    the handler's own message is logged rather than returned, because it can
+    embed the text of an upstream exception.
+    """
+    locator = payload.get("locator")
+    try:
+        response = handler(_legacy_request(request, payload))
+    except APIException:
+        raise
+    except Exception as exc:  # pylint: disable=broad-except
+        _translate(exc, course_key, locator, failure_message)
+        raise
+
+    body, status_code = _decode(response)
+    if status_code >= 400:
+        log.warning(
+            "YouTube transcript operation failed for locator %s under course %s: %s",
+            locator,
+            course_key,
+            body.get("status"),
+        )
+        raise ValidationError({"locator": [failure_message]})
+    return body
+
+
+def get_transcript_check_result(request, payload, course_key):
+    """Return the YouTube transcript status of the video named in ``payload``."""
+    return _run(check_transcripts, request, payload, course_key, CHECK_FAILED_MESSAGE)
+
+
+def import_transcripts(request, payload, course_key):
+    """Import the video's YouTube transcript and return the resulting record."""
+    return _run(replace_transcripts, request, payload, course_key, IMPORT_FAILED_MESSAGE)
diff --git a/cms/envs/devstack.py b/cms/envs/devstack.py
index 0576a35272af..d37de8f15e38 100644
--- a/cms/envs/devstack.py
+++ b/cms/envs/devstack.py
@@ -356,12 +356,17 @@ def should_show_debug_toolbar(request):  # pylint: disable=missing-function-docs
     'SERVE_INCLUDE_SCHEMA': False,
     # restrict spectacular to CMS API endpoints (cms/lib/spectacular.py):
     'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],
-    # remove the default schema path prefix to replace it with server-specific base paths:
-    'SCHEMA_PATH_PREFIX': '/api/contentstore',
-    'SCHEMA_PATH_PREFIX_TRIM': '/api/contentstore',
+    # The enum hook is drf-spectacular's default, restated because setting this
+    # key replaces the default list.
+    'POSTPROCESSING_HOOKS': [
+        'drf_spectacular.hooks.postprocess_schema_enums',
+        'cms.lib.spectacular.cms_mark_superseded_paths',
+    ],
+    # Used for tag extraction only. Paths are emitted in full so they resolve
+    # against the service-root SERVERS below.
+    'SCHEMA_PATH_PREFIX': r'/api/(contentstore|authoring)',
     'SERVERS': [
         {'url': AUTHORING_API_URL, 'description': 'Public'},  # noqa: F405
         {'url': f'http://{CMS_BASE}', 'description': 'Local'},
-        {'url': f'http://{CMS_BASE}/api/contentstore', 'description': 'CMS-contentstore'}
     ],
 }
diff --git a/cms/envs/production.py b/cms/envs/production.py
index b15caa2d1c14..929ed3b7f565 100644
--- a/cms/envs/production.py
+++ b/cms/envs/production.py
@@ -415,13 +415,18 @@ def get_env_setting(setting):
     'SERVE_INCLUDE_SCHEMA': False,
     # restrict spectacular to CMS API endpoints (cms/lib/spectacular.py):
     'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],
-    # remove the default schema path prefix to replace it with server-specific base paths:
-    'SCHEMA_PATH_PREFIX': '/api/contentstore',
-    'SCHEMA_PATH_PREFIX_TRIM': '/api/contentstore',
+    # The enum hook is drf-spectacular's default, restated because setting this
+    # key replaces the default list.
+    'POSTPROCESSING_HOOKS': [
+        'drf_spectacular.hooks.postprocess_schema_enums',
+        'cms.lib.spectacular.cms_mark_superseded_paths',
+    ],
+    # Used for tag extraction only. Paths are emitted in full so they resolve
+    # against the service-root SERVERS below.
+    'SCHEMA_PATH_PREFIX': r'/api/(contentstore|authoring)',
     'SERVERS': [
         {'url': AUTHORING_API_URL, 'description': 'Public'},  # noqa: F405
         {'url': f'https://{CMS_BASE}', 'description': 'Local'},  # noqa: F405
-        {'url': f'https://{CMS_BASE}/api/contentstore', 'description': 'CMS-contentstore'}  # noqa: F405
     ],
 }
 
diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py
index 90bce5668fec..abcc42838474 100644
--- a/cms/lib/spectacular.py
+++ b/cms/lib/spectacular.py
@@ -2,6 +2,17 @@
 
 import re
 
+# Legacy operations superseded by a conforming address under /api/authoring/.
+# Each is listed in the truncated spelling as well as the full one: the routes
+# make the final character optional, so both addresses resolve, and which one
+# the generator emits depends on how it renders that regex.
+SUPERSEDED_PATHS = (
+    "/api/contentstore/v0/youtube_transcripts/{course_id}/chec",
+    "/api/contentstore/v0/youtube_transcripts/{course_id}/check",
+    "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa",
+    "/api/contentstore/v0/youtube_transcripts/{course_id}/upload",
+)
+
 
 def cms_api_filter(endpoints):
     """
@@ -9,7 +20,7 @@ def cms_api_filter(endpoints):
     course-level endpoints.
     """
     filtered = []
-    CMS_PATH_PATTERN = re.compile(r"^/api/contentstore/v\d+/")
+    CMS_PATH_PATTERN = re.compile(r"^/api/(contentstore|authoring)/v\d+/")
 
     for path, path_regex, method, callback in endpoints:
         if (
@@ -22,3 +33,14 @@ def cms_api_filter(endpoints):
             filtered.append((path, path_regex, method, callback))
 
     return filtered
+
+
+def cms_mark_superseded_paths(result, generator, request, public):  # pylint: disable=unused-argument
+    """
+    Post-processing hook: mark the operations of superseded paths deprecated.
+    """
+    for path in SUPERSEDED_PATHS:
+        for operation in result.get("paths", {}).get(path, {}).values():
+            if isinstance(operation, dict):
+                operation["deprecated"] = True
+    return result
diff --git a/cms/lib/tests/__init__.py b/cms/lib/tests/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/cms/lib/tests/test_spectacular.py b/cms/lib/tests/test_spectacular.py
new file mode 100644
index 000000000000..653c7f361cd0
--- /dev/null
+++ b/cms/lib/tests/test_spectacular.py
@@ -0,0 +1,120 @@
+"""Tests for the CMS drf-spectacular hooks."""
+
+from pathlib import Path
+from unittest import TestCase
+
+from cms.lib.spectacular import SUPERSEDED_PATHS, cms_api_filter, cms_mark_superseded_paths
+
+
+def _endpoint(path):
+    """Return an endpoint tuple shaped as the pre-processing hook receives it."""
+    return (path, path, "GET", object())
+
+
+class CmsApiFilterTest(TestCase):
+    """Which mounts reach the generated schema."""
+
+    @staticmethod
+    def _admitted(path):
+        """Return whether the pre-processing hook keeps path."""
+        return bool(cms_api_filter([_endpoint(path)]))
+
+    def test_the_authoring_mount_is_admitted(self):
+        assert self._admitted("/api/authoring/v1/courses/course-v1:a+b+c/youtube_transcript_checks/")
+
+    def test_the_contentstore_mount_is_still_admitted(self):
+        assert self._admitted("/api/contentstore/v0/youtube_transcripts/course-v1:a+b+c/check")
+        assert self._admitted("/api/contentstore/v4/home/courses/")
+
+    def test_the_hand_listed_discussions_path_is_still_admitted(self):
+        assert self._admitted("/api/courses/course-v1:a+b+c/bulk_enable_disable_discussions")
+
+    def test_an_unrelated_mount_is_refused(self):
+        assert not self._admitted("/api/user/v1/accounts/")
+        assert not self._admitted("/api/authoring/courses/")
+        assert not self._admitted("/authoring/v1/courses/")
+
+    def test_the_filter_preserves_the_endpoint_tuples_it_keeps(self):
+        kept = _endpoint("/api/authoring/v1/courses/")
+        dropped = _endpoint("/api/user/v1/accounts/")
+        assert cms_api_filter([kept, dropped]) == [kept]
+
+
+class CmsMarkSupersededPathsTest(TestCase):
+    """Which operations the post-processing hook marks deprecated."""
+
+    def _run(self, schema):
+        return cms_mark_superseded_paths(schema, generator=None, request=None, public=True)
+
+    def test_every_operation_of_a_superseded_path_is_marked(self):
+        schema = {"paths": {path: {"get": {}} for path in SUPERSEDED_PATHS}}
+        result = self._run(schema)
+        for path in SUPERSEDED_PATHS:
+            assert result["paths"][path]["get"]["deprecated"] is True
+
+    def test_both_spellings_of_each_superseded_path_are_listed(self):
+        assert set(SUPERSEDED_PATHS) == {
+            "/api/contentstore/v0/youtube_transcripts/{course_id}/chec",
+            "/api/contentstore/v0/youtube_transcripts/{course_id}/check",
+            "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa",
+            "/api/contentstore/v0/youtube_transcripts/{course_id}/upload",
+        }
+
+    def test_the_conforming_paths_are_left_unmarked(self):
+        conforming = "/api/authoring/v1/courses/{course_key}/youtube_transcript_checks/"
+        result = self._run({"paths": {conforming: {"get": {"operationId": "x"}}}})
+        assert result["paths"][conforming]["get"] == {"operationId": "x"}
+
+    def test_an_unrelated_contentstore_path_is_left_unmarked(self):
+        other = "/api/contentstore/v0/advanced_settings/{course_id}"
+        result = self._run({"paths": {other: {"get": {}}}})
+        assert "deprecated" not in result["paths"][other]["get"]
+
+    def test_path_level_keys_are_not_treated_as_operations(self):
+        path = SUPERSEDED_PATHS[0]
+        result = self._run({"paths": {path: {"parameters": [], "get": {}}}})
+        assert result["paths"][path]["parameters"] == []
+        assert result["paths"][path]["get"]["deprecated"] is True
+
+    def test_a_schema_without_the_superseded_paths_is_returned_unchanged(self):
+        schema = {"paths": {}}
+        assert self._run(schema) == {"paths": {}}
+
+
+class SpectacularSettingsTest(TestCase):
+    """
+    The service settings the hooks depend on.
+
+    Read from the environment modules that define them, because the test
+    settings module does not configure the schema at all.
+    """
+
+    SETTINGS_MODULES = ("cms/envs/devstack.py", "cms/envs/production.py")
+
+    def _source(self, module):
+        return (Path(__file__).resolve().parents[3] / module).read_text()
+
+    def test_both_hooks_are_configured_in_every_environment(self):
+        for module in self.SETTINGS_MODULES:
+            source = self._source(module)
+            assert "'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter']" in source, module
+            assert "'cms.lib.spectacular.cms_mark_superseded_paths'," in source, module
+
+    def test_the_default_enum_hook_is_kept_alongside_the_new_one(self):
+        """Setting the key replaces drf-spectacular's default list, so it is restated."""
+        for module in self.SETTINGS_MODULES:
+            source = self._source(module)
+            assert "'drf_spectacular.hooks.postprocess_schema_enums'," in source, module
+
+    def test_no_prefix_is_trimmed_so_paths_are_emitted_in_full(self):
+        for module in self.SETTINGS_MODULES:
+            assert "SCHEMA_PATH_PREFIX_TRIM" not in self._source(module), module
+
+    def test_the_tag_prefix_covers_both_mounts(self):
+        for module in self.SETTINGS_MODULES:
+            source = self._source(module)
+            assert "'SCHEMA_PATH_PREFIX': r'/api/(contentstore|authoring)'," in source, module
+
+    def test_no_server_advertises_a_single_mount_as_its_root(self):
+        for module in self.SETTINGS_MODULES:
+            assert "CMS-contentstore" not in self._source(module), module
diff --git a/cms/urls.py b/cms/urls.py
index c0f96f489bb8..e3ee62e81720 100644
--- a/cms/urls.py
+++ b/cms/urls.py
@@ -13,6 +13,7 @@
 from django.views.generic import RedirectView
 from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
 from edx_api_doc_tools import make_docs_urls
+from edx_rest_framework_extensions.url_converters import register_url_converters
 
 import openedx.core.djangoapps.common_views.xblock
 import openedx.core.djangoapps.debug.views
@@ -27,6 +28,10 @@
 from openedx.core.djangoapps.password_policy.forms import PasswordPolicyAwareAdminAuthForm
 
 django_autodiscover()
+
+# Must run before any pattern below that uses <course_key:...> or <usage_key:...>.
+register_url_converters()
+
 admin.site.site_header = _('Studio Administration')
 admin.site.site_title = admin.site.site_header
 
@@ -356,6 +361,12 @@
     path('api/contentstore/', include('cms.djangoapps.contentstore.rest_api.urls'))
 ]
 
+# Conforming addresses, mounted beside their legacy /api/contentstore/ routes
+# for the deprecation window.
+urlpatterns += [
+    path('api/authoring/v1/', include('cms.djangoapps.contentstore.rest_api.v1.authoring_urls')),
+]
+
 # Content tagging
 urlpatterns += [
     path('api/content_tagging/', include(('openedx.core.djangoapps.content_tagging.urls', 'content_tagging'))),

From d0c94cbed21a8e089f71bdbe23a1d280256afc28 Mon Sep 17 00:00:00 2001
From: Muhammad Faraz  Maqsood <faraz.maqsood@arbisoft.com>
Date: Tue, 6 Oct 2026 18:25:15 +0500
Subject: [PATCH 2/4] fix: address review feedback on the youtube transcripts
 APIs

- Publish full paths from cms/envs/common.py as well. cms.envs.development
  inherits these settings to generate the committed docs/cms-openapi.yaml,
  which otherwise mixed trimmed /v0/... paths with untrimmed
  /api/authoring/v1/... ones and marked nothing deprecated. Drop
  SCHEMA_PATH_PREFIX_TRIM, widen SCHEMA_PATH_PREFIX to both mounts, and add
  the hook that marks the superseded v0 paths deprecated.
- Require a "youtube" entry in the import's videos, so a missing one is
  reported on videos rather than as a failure on locator.
- Test a locator that is neither a course nor a V2 library block, which the
  handlers reject with TranscriptsRequestValidationException.
---
 .../v1/serializers/youtube_transcripts.py     |  6 +++++
 .../views/tests/test_youtube_transcripts.py   | 27 ++++++++++++++++++-
 cms/envs/common.py                            | 14 +++++++---
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
index b5299f490692..e06f5d6f8928 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/serializers/youtube_transcripts.py
@@ -51,6 +51,12 @@ class YoutubeTranscriptImportRequestSerializer(serializers.Serializer):
         help_text='Video sources declared on the block. An entry of type "youtube" is required.',
     )
 
+    def validate_videos(self, value):
+        """Require the YouTube source the transcript is imported from."""
+        if not any(video.get("type") == "youtube" for video in value):
+            raise serializers.ValidationError('An entry of type "youtube" is required.')
+        return value
+
     class Meta:
         ref_name = "YoutubeTranscriptImportRequest"
 
diff --git a/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
index 2ce36990b072..5dde88315105 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
@@ -47,6 +47,8 @@
 IMPORT_URL_NAME = "authoring_v1:youtube_transcript_import_list"
 LEGACY_CHECK_URL_NAME = "cms.djangoapps.contentstore:v0:cms_api_youtube_transcripts_check"
 LEGACY_IMPORT_URL_NAME = "cms.djangoapps.contentstore:v0:cms_api_youtube_transcripts_upload"
+# A V1 content library block: neither a course nor a V2 library context.
+UNSUPPORTED_CONTEXT_LOCATOR = "lib-block-v1:edX+Lib+2024+type@video+block@abc"
 
 YOUTUBE_ID = "test_yt_id"
 
@@ -370,7 +372,9 @@ def test_check_rejects_a_payload_without_a_locator(self):
         assert response.json()["errors"] == {"locator": ["This field is required."]}
 
     def test_import_rejects_a_payload_without_a_locator(self):
-        response = self.post_import(user=self.course_instructor, payload={"videos": []})
+        payload = self.payload()
+        del payload["locator"]
+        response = self.post_import(user=self.course_instructor, payload=payload)
         assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
         assert response.json()["errors"] == {"locator": ["This field is required."]}
 
@@ -434,6 +438,27 @@ def test_import_without_a_youtube_source_is_rejected(self):
             payload=self.payload(videos=[{"type": "html5", "video": "v1", "mode": "mp4"}]),
         )
         assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {"videos": ['An entry of type "youtube" is required.']}
+
+    def test_check_reports_a_block_in_an_unsupported_context_as_a_rejected_request(self):
+        """A locator that is neither a course nor a V2 library block cannot be handled."""
+        response = self.get_check(
+            user=self.course_instructor, payload=self.payload(locator=UNSUPPORTED_CONTEXT_LOCATOR),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {
+            "locator": ["The transcript status for this video could not be determined."],
+        }
+
+    def test_import_reports_a_block_in_an_unsupported_context_as_a_rejected_request(self):
+        """A locator that is neither a course nor a V2 library block cannot be handled."""
+        response = self.post_import(
+            user=self.course_instructor, payload=self.payload(locator=UNSUPPORTED_CONTEXT_LOCATOR),
+        )
+        assert_error_envelope(response, expected_status=400, expected_type_slug="validation")
+        assert response.json()["errors"] == {
+            "locator": ["The YouTube transcript could not be imported for this video."],
+        }
 
     def test_a_youtube_download_failure_does_not_leak_its_message(self):
         from openedx.core.djangoapps.video_config.transcripts_utils import (  # noqa: PLC0415
diff --git a/cms/envs/common.py b/cms/envs/common.py
index 13d3676a2740..8430f7a65af8 100644
--- a/cms/envs/common.py
+++ b/cms/envs/common.py
@@ -1329,10 +1329,16 @@ def _should_send_xblock_events(settings):
     'SERVE_INCLUDE_SCHEMA': False,
     # Restrict the schema to the Authoring API's endpoints (cms/lib/spectacular.py).
     'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],
-    # Trim the shared prefix from the published paths; consumers supply it
-    # through their base URL.
-    'SCHEMA_PATH_PREFIX': '/api/contentstore',
-    'SCHEMA_PATH_PREFIX_TRIM': '/api/contentstore',
+    # The enum hook is drf-spectacular's default, restated because setting this
+    # key replaces the default list.
+    'POSTPROCESSING_HOOKS': [
+        'drf_spectacular.hooks.postprocess_schema_enums',
+        'cms.lib.spectacular.cms_mark_superseded_paths',
+    ],
+    # Used for tag extraction only. Paths are published in full, from the
+    # service root, so /api/contentstore and /api/authoring resolve against the
+    # same base URL.
+    'SCHEMA_PATH_PREFIX': r'/api/(contentstore|authoring)',
 }
 
 ################### Studio Search (beta), using Meilisearch ###################

From 6fd7addb2f722eb05fd0f61a349f5015f58f926c Mon Sep 17 00:00:00 2001
From: Muhammad Faraz  Maqsood <faraz.maqsood@arbisoft.com>
Date: Tue, 6 Oct 2026 19:37:37 +0500
Subject: [PATCH 3/4] fix: stop registering error types in the youtube
 transcripts service

The registry in edx_rest_framework_extensions.errors is process-wide, so
registering MethodNotAllowed and ParseError here changed the error type of
every standardized Studio endpoint, not only these two. Left to an
edx-drf-extensions follow-up, as in #39102; the 405 tests assert the status
only.
---
 .../rest_api/v1/views/tests/test_youtube_transcripts.py  | 8 ++------
 .../rest_api/v1/youtube_transcripts_service.py           | 9 ---------
 2 files changed, 2 insertions(+), 15 deletions(-)

diff --git a/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
index 5dde88315105..f1c7cf6935f4 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/views/tests/test_youtube_transcripts.py
@@ -336,16 +336,12 @@ def test_import_keeps_an_existing_video_id(self):
     def test_import_is_not_reachable_by_get(self):
         self.api_client.force_authenticate(user=self.course_instructor)
         response = self.api_client.get(self.import_url())
-        assert_error_envelope(
-            response, expected_status=405, expected_type_slug="method-not-allowed",
-        )
+        assert_error_envelope(response, expected_status=405)
 
     def test_check_is_not_reachable_by_post(self):
         self.api_client.force_authenticate(user=self.course_instructor)
         response = self.api_client.post(self.check_url(), self.payload(), format="json")
-        assert_error_envelope(
-            response, expected_status=405, expected_type_slug="method-not-allowed",
-        )
+        assert_error_envelope(response, expected_status=405)
 
 
 @patch(DOWNLOAD_PATH, Mock(return_value=[["en", SJSON_TRANSCRIPT_CONTENT]]))
diff --git a/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
index ae856bf8b056..bdbde61b94c4 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
@@ -5,12 +5,9 @@
 
 from django.core.exceptions import PermissionDenied as DjangoPermissionDenied
 from django.http import Http404, QueryDict
-from edx_rest_framework_extensions.errors import register_error_type
 from rest_framework.exceptions import (
     APIException,
-    MethodNotAllowed,
     NotFound,
-    ParseError,
     PermissionDenied,
     ValidationError,
 )
@@ -21,12 +18,6 @@
 
 log = logging.getLogger(__name__)
 
-# Neither exception is in the library's built-in classification catalog, so
-# without these registrations a wrong verb or an unparseable body would be
-# reported to the client as an internal server error at a 4xx status.
-register_error_type(MethodNotAllowed, "method-not-allowed", "Method Not Allowed")
-register_error_type(ParseError, "parse-error", "Malformed Request")
-
 CHECK_FAILED_MESSAGE = "The transcript status for this video could not be determined."
 IMPORT_FAILED_MESSAGE = "The YouTube transcript could not be imported for this video."
 FORBIDDEN_MESSAGE = "You do not have permission to edit this video."

From 7b12715a5de9f575c9535f5986b10745cc6a2d15 Mon Sep 17 00:00:00 2001
From: Muhammad Faraz  Maqsood <faraz.maqsood@arbisoft.com>
Date: Wed, 7 Oct 2026 12:47:24 +0500
Subject: [PATCH 4/4] docs: note why a YouTube failure is a 400 in the
 transcripts service

A failure on YouTube's side is reported as a 400, matching v0. It can
become a 502 once edx-drf-extensions registers an error type for
upstream failures.
---
 .../contentstore/rest_api/v1/youtube_transcripts_service.py    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
index bdbde61b94c4..e34ad8fd6056 100644
--- a/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
+++ b/cms/djangoapps/contentstore/rest_api/v1/youtube_transcripts_service.py
@@ -107,6 +107,9 @@ def _run(handler, request, payload, course_key, failure_message):
             course_key,
             body.get("status"),
         )
+        # A failure on YouTube's side is a 400 here, deliberately, as in v0.
+        # It can become a 502 once edx-drf-extensions registers an error type
+        # for upstream failures.
         raise ValidationError({"locator": [failure_message]})
     return body