fix: Correct V2 move endpoint to use entity ID in URL path

The V2 move endpoint was incorrectly accepting an identifier in the request
body, violating V2 API design principles. Fixed to use entity ID in the URL
path for consistency with other V2 endpoints.

Changes:
- Add MoveEntityRequestV2 schema with only destination_path field
- Update move endpoint from POST /knowledge/move to PUT /knowledge/entities/{entity_id}/move
- Entity ID now in URL path, not request body
- Updated endpoint implementation to fetch entity by ID first
- Updated test to use new endpoint structure

Before:
  POST /v2/projects/{project_id}/knowledge/move
  Body: { "identifier": "...", "destination_path": "..." }

After:
  PUT /v2/projects/{project_id}/knowledge/entities/{entity_id}/move
  Body: { "destination_path": "..." }

All 180 V2 API tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Joe P <joe@basicmemory.com>

Author: jope-bm

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -25,11 +25,12 @@
 )
 from basic_memory.schemas import EntityResponse, DeleteEntitiesResponse
 from basic_memory.schemas.base import Entity
-from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
+from basic_memory.schemas.request import EditEntityRequest
 from basic_memory.schemas.v2 import (
     EntityResolveRequest,
     EntityResolveResponse,
     EntityResponseV2,
+    MoveEntityRequestV2,
 )
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge-v2"])
@@ -351,44 +352,53 @@ async def delete_entity_by_id(
 ## Move endpoint
 
 
-@router.post("/move", response_model=EntityResponseV2)
+@router.put("/entities/{entity_id}/move", response_model=EntityResponseV2)
 async def move_entity(
     project_id: ProjectIdPathDep,
-    data: MoveEntityRequest,
+    entity_id: int,
+    data: MoveEntityRequestV2,
     background_tasks: BackgroundTasks,
     entity_service: EntityServiceV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
     project_config: ProjectConfigV2Dep,
     app_config: AppConfigDep,
     search_service: SearchServiceV2Dep,
 ) -> EntityResponseV2:
     """Move an entity to a new file location.
 
-    Note: Identifier in request can be an entity ID or legacy identifier.
+    V2 API uses entity ID in the URL path for stable references.
     The entity ID will remain stable after the move.
 
     Args:
-        data: Move request with identifier and destination path
+        project_id: Project ID from URL path
+        entity_id: Entity ID from URL path (primary identifier)
+        data: Move request with destination path only
 
     Returns:
         Updated entity with new file path
     """
     logger.info(
-        f"API v2 request: move_entity identifier='{data.identifier}', destination='{data.destination_path}'"
+        f"API v2 request: move_entity entity_id={entity_id}, destination='{data.destination_path}'"
     )
 
     try:
-        # Move the entity
+        # First, get the entity by ID to verify it exists
+        entity = await entity_repository.find_by_id(entity_id)
+        if not entity:
+            raise HTTPException(status_code=404, detail=f"Entity not found: {entity_id}")
+
+        # Move the entity using its current file path as identifier
         moved_entity = await entity_service.move_entity(
-            identifier=data.identifier,
+            identifier=entity.file_path,  # Use file path for resolution
             destination_path=data.destination_path,
             project_config=project_config,
             app_config=app_config,
         )
 
         # Reindex at new location
-        entity = await entity_service.link_resolver.resolve_link(data.destination_path)
-        if entity:
-            await search_service.index_entity(entity, background_tasks=background_tasks)
+        reindexed_entity = await entity_service.link_resolver.resolve_link(data.destination_path)
+        if reindexed_entity:
+            await search_service.index_entity(reindexed_entity, background_tasks=background_tasks)
 
         result = EntityResponseV2.model_validate(moved_entity)
 
@@ -398,6 +408,8 @@ async def move_entity(
 
         return result
 
+    except HTTPException:
+        raise
     except Exception as e:
         logger.error(f"Error moving entity: {e}")
         raise HTTPException(status_code=400, detail=str(e))

src/basic_memory/schemas/v2/__init__.py

@@ -4,6 +4,7 @@
     EntityResolveRequest,
     EntityResolveResponse,
     EntityResponseV2,
+    MoveEntityRequestV2,
 )
 from basic_memory.schemas.v2.resource import (
     CreateResourceRequest,
@@ -15,6 +16,7 @@
     "EntityResolveRequest",
     "EntityResolveResponse",
     "EntityResponseV2",
+    "MoveEntityRequestV2",
     "CreateResourceRequest",
     "UpdateResourceRequest",
     "ResourceResponse",

src/basic_memory/schemas/v2/entity.py

@@ -40,6 +40,21 @@ class EntityResolveResponse(BaseModel):
     )
 
 
+class MoveEntityRequestV2(BaseModel):
+    """V2 request schema for moving an entity to a new file location.
+
+    In V2 API, the entity ID is provided in the URL path, so this request
+    only needs the destination path.
+    """
+
+    destination_path: str = Field(
+        ...,
+        description="New file path for the entity (relative to project root)",
+        min_length=1,
+        max_length=500,
+    )
+
+
 class EntityResponseV2(BaseModel):
     """V2 entity response with ID as the primary field.
 

tests/api/v2/test_knowledge_router.py

@@ -347,12 +347,13 @@ async def test_move_entity(client: AsyncClient, file_service, v2_project_url, en
     assert created_entity.id is not None
     original_id = created_entity.id
 
-    # Move it to a new folder (use permalink for identifier in v2)
+    # Move it to a new folder (V2 uses entity ID in path)
     move_data = {
-        "identifier": created_entity.permalink,  # Use permalink as identifier
         "destination_path": "moved/MovedEntity.md",
     }
-    response = await client.post(f"{v2_project_url}/knowledge/move", json=move_data)
+    response = await client.put(
+        f"{v2_project_url}/knowledge/entities/{created_entity.id}/move", json=move_data
+    )
 
     assert response.status_code == 200
     moved_entity = EntityResponseV2.model_validate(response.json())