feat(gateway): dual-mount legacy routers on /api and /api/v1 (Stage 1 PR5)

Strip /api prefix from 13 legacy router APIRouter() declarations and dual-mount
each on prefix="/api" (backward compat) and prefix="/api/v1" (versioned surface)
in app.py. Auth, service-accounts, api-keys, assistants-compat remain single-mount.
Update 10 test files to pass prefix="/api" when directly including stripped routers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/app/gateway/app.py

@@ -381,56 +381,72 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
             )
 
     # Include routers
-    # Models API is mounted at /api/models
-    app.include_router(models.router)
+    # Legacy routers are dual-mounted on /api (backward compat) and /api/v1 (versioned).
+    # The deprecation middleware (Task 5.1) stamps X-API-Deprecated on /api responses.
 
-    # MCP API is mounted at /api/mcp
-    app.include_router(mcp.router)
+    # Models API — /api/models and /api/v1/models
+    app.include_router(models.router, prefix="/api")
+    app.include_router(models.router, prefix="/api/v1")
 
-    # Memory API is mounted at /api/memory
-    app.include_router(memory.router)
+    # MCP API — /api/mcp and /api/v1/mcp
+    app.include_router(mcp.router, prefix="/api")
+    app.include_router(mcp.router, prefix="/api/v1")
 
-    # Skills API is mounted at /api/skills
-    app.include_router(skills.router)
+    # Memory API — /api/memory and /api/v1/memory
+    app.include_router(memory.router, prefix="/api")
+    app.include_router(memory.router, prefix="/api/v1")
 
-    # Artifacts API is mounted at /api/threads/{thread_id}/artifacts
-    app.include_router(artifacts.router)
+    # Skills API — /api/skills and /api/v1/skills
+    app.include_router(skills.router, prefix="/api")
+    app.include_router(skills.router, prefix="/api/v1")
 
-    # Uploads API is mounted at /api/threads/{thread_id}/uploads
-    app.include_router(uploads.router)
+    # Artifacts API — /api/threads/{thread_id}/artifacts and /api/v1/threads/{thread_id}/artifacts
+    app.include_router(artifacts.router, prefix="/api")
+    app.include_router(artifacts.router, prefix="/api/v1")
 
-    # Thread cleanup API is mounted at /api/threads/{thread_id}
-    app.include_router(threads.router)
+    # Uploads API — /api/threads/{thread_id}/uploads and /api/v1/threads/{thread_id}/uploads
+    app.include_router(uploads.router, prefix="/api")
+    app.include_router(uploads.router, prefix="/api/v1")
 
-    # Agents API is mounted at /api/agents
-    app.include_router(agents.router)
+    # Threads API — /api/threads/{thread_id} and /api/v1/threads/{thread_id}
+    app.include_router(threads.router, prefix="/api")
+    app.include_router(threads.router, prefix="/api/v1")
 
-    # Suggestions API is mounted at /api/threads/{thread_id}/suggestions
-    app.include_router(suggestions.router)
+    # Agents API — /api/agents and /api/v1/agents
+    app.include_router(agents.router, prefix="/api")
+    app.include_router(agents.router, prefix="/api/v1")
 
-    # Channels API is mounted at /api/channels
-    app.include_router(channels.router)
+    # Suggestions API — /api/threads/{thread_id}/suggestions and /api/v1/threads/{thread_id}/suggestions
+    app.include_router(suggestions.router, prefix="/api")
+    app.include_router(suggestions.router, prefix="/api/v1")
 
-    # Assistants compatibility API (LangGraph Platform stub)
+    # Channels API — /api/channels and /api/v1/channels
+    app.include_router(channels.router, prefix="/api")
+    app.include_router(channels.router, prefix="/api/v1")
+
+    # Assistants compatibility API (LangGraph Platform stub) — intentionally NOT dual-mounted
     app.include_router(assistants_compat.router)
 
-    # Auth API is mounted at /api/v1/auth
+    # Auth API — /api/v1/auth only (already versioned; must NOT get an /api/auth twin)
     app.include_router(auth.router)
 
-    # Service Accounts API is mounted at /api/v1/service-accounts
+    # Service Accounts API — /api/v1/service-accounts only (already versioned)
     app.include_router(service_accounts.router)
 
-    # API Keys API is mounted at /api/v1/api-keys
+    # API Keys API — /api/v1/api-keys only (already versioned)
     app.include_router(api_keys.router)
 
-    # Feedback API is mounted at /api/threads/{thread_id}/runs/{run_id}/feedback
-    app.include_router(feedback.router)
+    # Feedback API — /api/threads/{thread_id}/runs/{run_id}/feedback and /api/v1/... twin
+    app.include_router(feedback.router, prefix="/api")
+    app.include_router(feedback.router, prefix="/api/v1")
 
-    # Thread Runs API (LangGraph Platform-compatible runs lifecycle)
-    app.include_router(thread_runs.router)
+    # Thread Runs API — /api/threads/{thread_id}/runs and /api/v1/... twin
+    app.include_router(thread_runs.router, prefix="/api")
+    app.include_router(thread_runs.router, prefix="/api/v1")
 
-    # Stateless Runs API (stream/wait without a pre-existing thread)
-    app.include_router(runs.router)
+    # Stateless Runs API — /api/runs and /api/v1/runs
+    app.include_router(runs.router, prefix="/api")
+    app.include_router(runs.router, prefix="/api/v1")
 
     @app.get("/health", tags=["health"])
     async def health_check() -> dict:

backend/app/gateway/routers/agents.py

@@ -14,7 +14,7 @@ from deerflow.config.paths import get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api", tags=["agents"])
+router = APIRouter(tags=["agents"])
 
 AGENT_NAME_PATTERN = re.compile(r"^[A-Za-z0-9-]+$")
 

backend/app/gateway/routers/artifacts.py

@@ -12,7 +12,7 @@ from app.gateway.path_utils import resolve_thread_virtual_path
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api", tags=["artifacts"])
+router = APIRouter(tags=["artifacts"])
 
 ACTIVE_CONTENT_MIME_TYPES = {
     "text/html",

backend/app/gateway/routers/channels.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api/channels", tags=["channels"])
+router = APIRouter(prefix="/channels", tags=["channels"])
 
 
 class ChannelStatusResponse(BaseModel):

backend/app/gateway/routers/feedback.py

@@ -16,7 +16,7 @@ from app.gateway.authz import require_permission
 from app.gateway.deps import get_current_user, get_feedback_repo, get_run_store
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/threads", tags=["feedback"])
+router = APIRouter(prefix="/threads", tags=["feedback"])
 
 
 # ---------------------------------------------------------------------------

backend/app/gateway/routers/mcp.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, Field
 from deerflow.config.extensions_config import ExtensionsConfig, get_extensions_config, reload_extensions_config
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api", tags=["mcp"])
+router = APIRouter(tags=["mcp"])
 
 
 class McpOAuthConfigResponse(BaseModel):

backend/app/gateway/routers/memory.py

@@ -15,7 +15,7 @@ from deerflow.agents.memory.updater import (
 from deerflow.config.memory_config import get_memory_config
 from deerflow.runtime.user_context import get_effective_user_id
 
-router = APIRouter(prefix="/api", tags=["memory"])
+router = APIRouter(tags=["memory"])
 
 
 class ContextSection(BaseModel):

backend/app/gateway/routers/models.py

@@ -4,7 +4,7 @@ from pydantic import BaseModel, Field
 from app.gateway.deps import get_config
 from deerflow.config.app_config import AppConfig
 
-router = APIRouter(prefix="/api", tags=["models"])
+router = APIRouter(tags=["models"])
 
 
 class ModelResponse(BaseModel):

backend/app/gateway/routers/runs.py

@@ -21,7 +21,7 @@ from app.gateway.services import sse_consumer, start_run
 from deerflow.runtime import serialize_channel_values
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/runs", tags=["runs"])
+router = APIRouter(prefix="/runs", tags=["runs"])
 
 
 def _resolve_thread_id(body: RunCreateRequest) -> str:

backend/app/gateway/routers/skills.py

@@ -18,7 +18,7 @@ from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api", tags=["skills"])
+router = APIRouter(tags=["skills"])
 
 
 class SkillResponse(BaseModel):

backend/app/gateway/routers/suggestions.py

@@ -12,7 +12,7 @@ from deerflow.models import create_chat_model
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api", tags=["suggestions"])
+router = APIRouter(tags=["suggestions"])
 
 
 class SuggestionMessage(BaseModel):

backend/app/gateway/routers/thread_runs.py

@@ -25,7 +25,7 @@ from app.gateway.services import sse_consumer, start_run
 from deerflow.runtime import RunRecord, serialize_channel_values
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/threads", tags=["runs"])
+router = APIRouter(prefix="/threads", tags=["runs"])
 
 
 # ---------------------------------------------------------------------------

backend/app/gateway/routers/threads.py

@@ -29,7 +29,7 @@ from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.utils.time import coerce_iso, now_iso
 
 logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/threads", tags=["threads"])
+router = APIRouter(prefix="/threads", tags=["threads"])
 
 
 # Metadata keys that the server controls; clients are not allowed to set

backend/app/gateway/routers/uploads.py

@@ -30,7 +30,7 @@ from deerflow.utils.file_conversion import CONVERTIBLE_EXTENSIONS, convert_file_
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api/threads/{thread_id}/uploads", tags=["uploads"])
+router = APIRouter(prefix="/threads/{thread_id}/uploads", tags=["uploads"])
 
 UPLOAD_CHUNK_SIZE = 8192
 DEFAULT_MAX_FILES = 10