feat: restructure API URLs for better clarity and consistency

Implement the API URL restructuring as described in issue #17:

- Add /v1/ prefix for versioning
- Use consistent resource-oriented naming 
- Replace session-based URLs with working-memory URLs

Breaking changes:
- GET /sessions/ → GET /v1/working-memory/
- GET/PUT/DELETE /sessions/{id}/memory → GET/PUT/DELETE /v1/working-memory/{id}
- POST /long-term-memory → POST /v1/long-term-memory/
- POST /long-term-memory/search → POST /v1/long-term-memory/search
- POST /memory/search → POST /v1/memory/search
- POST /memory-prompt → POST /v1/memory/prompt
- GET /health → GET /v1/health

Updated:
- API routes in api.py and healthcheck.py
- Client library in client/api.py
- All tests in test_api.py  
- Documentation in docs/ and CLAUDE.md
- Manual testing examples in manual_oauth_qa/

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

Co-Authored-By: abrookins <[email protected]>

Author: claude[bot]

CLAUDE.md

@@ -191,10 +191,10 @@ ENABLE_NER=true
 ## API Interfaces
 
 ### REST API (Port 8000)
-- Session management (`/sessions/`)
-- Working memory operations (`/sessions/{id}/memory`)
-- Long-term memory search (`/memories/search`)
-- Memory hydration (`/memories/hydrate`)
+- Session management (`/v1/working-memory/`)
+- Working memory operations (`/v1/working-memory/{id}`)
+- Long-term memory search (`/v1/long-term-memory/search`)
+- Memory hydration (`/v1/memory/prompt`)
 
 ### MCP Server (Port 9000)
 - `create_long_term_memories` - Store persistent memories

agent_memory_server/api.py

@@ -136,7 +136,7 @@ async def _summarize_working_memory(
     return updated_memory
 
 
-@router.get("/sessions/", response_model=SessionListResponse)
+@router.get("/v1/working-memory/", response_model=SessionListResponse)
 async def list_sessions(
     options: GetSessionsQuery = Depends(),
     current_user: UserInfo = Depends(get_current_user),
@@ -165,7 +165,7 @@ async def list_sessions(
     )
 
 
-@router.get("/sessions/{session_id}/memory", response_model=WorkingMemoryResponse)
+@router.get("/v1/working-memory/{session_id}", response_model=WorkingMemoryResponse)
 async def get_session_memory(
     session_id: str,
     namespace: str | None = None,
@@ -219,7 +219,7 @@ async def get_session_memory(
     return working_mem
 
 
-@router.put("/sessions/{session_id}/memory", response_model=WorkingMemoryResponse)
+@router.put("/v1/working-memory/{session_id}", response_model=WorkingMemoryResponse)
 async def put_session_memory(
     session_id: str,
     memory: WorkingMemory,
@@ -296,7 +296,7 @@ async def put_session_memory(
     return updated_memory
 
 
-@router.delete("/sessions/{session_id}/memory", response_model=AckResponse)
+@router.delete("/v1/working-memory/{session_id}", response_model=AckResponse)
 async def delete_session_memory(
     session_id: str,
     namespace: str | None = None,
@@ -326,7 +326,7 @@ async def delete_session_memory(
     return AckResponse(status="ok")
 
 
-@router.post("/long-term-memory", response_model=AckResponse)
+@router.post("/v1/long-term-memory/", response_model=AckResponse)
 async def create_long_term_memory(
     payload: CreateMemoryRecordRequest,
     background_tasks=Depends(get_background_tasks),
@@ -364,7 +364,7 @@ async def create_long_term_memory(
     return AckResponse(status="ok")
 
 
-@router.post("/long-term-memory/search", response_model=MemoryRecordResultsResponse)
+@router.post("/v1/long-term-memory/search", response_model=MemoryRecordResultsResponse)
 async def search_long_term_memory(
     payload: SearchRequest,
     current_user: UserInfo = Depends(get_current_user),
@@ -401,7 +401,7 @@ async def search_long_term_memory(
     return await long_term_memory.search_long_term_memories(**kwargs)
 
 
-@router.post("/memory/search", response_model=MemoryRecordResultsResponse)
+@router.post("/v1/memory/search", response_model=MemoryRecordResultsResponse)
 async def search_memory(
     payload: SearchRequest,
     current_user: UserInfo = Depends(get_current_user),
@@ -448,7 +448,7 @@ async def search_memory(
     return await long_term_memory.search_memories(**kwargs)
 
 
-@router.post("/memory-prompt", response_model=MemoryPromptResponse)
+@router.post("/v1/memory/prompt", response_model=MemoryPromptResponse)
 async def memory_prompt(
     params: MemoryPromptRequest,
     current_user: UserInfo = Depends(get_current_user),

agent_memory_server/client/api.py

@@ -116,7 +116,7 @@ async def health_check(self) -> HealthCheckResponse:
         Returns:
             HealthCheckResponse with current server timestamp
         """
-        response = await self._client.get("/health")
+        response = await self._client.get("/v1/health")
         response.raise_for_status()
         return HealthCheckResponse(**response.json())
 
@@ -143,7 +143,7 @@ async def list_sessions(
         elif self.config.default_namespace is not None:
             params["namespace"] = self.config.default_namespace
 
-        response = await self._client.get("/sessions/", params=params)
+        response = await self._client.get("/v1/working-memory/", params=params)
         response.raise_for_status()
         return SessionListResponse(**response.json())
 
@@ -188,7 +188,7 @@ async def get_session_memory(
             params["context_window_max"] = context_window_max
 
         response = await self._client.get(
-            f"/sessions/{session_id}/memory", params=params
+            f"/v1/working-memory/{session_id}", params=params
         )
         response.raise_for_status()
         return WorkingMemoryResponse(**response.json())
@@ -211,7 +211,7 @@ async def put_session_memory(
             memory.namespace = self.config.default_namespace
 
         response = await self._client.put(
-            f"/sessions/{session_id}/memory",
+            f"/v1/working-memory/{session_id}",
             json=memory.model_dump(exclude_none=True, mode="json"),
         )
         response.raise_for_status()
@@ -237,7 +237,7 @@ async def delete_session_memory(
             params["namespace"] = self.config.default_namespace
 
         response = await self._client.delete(
-            f"/sessions/{session_id}/memory", params=params
+            f"/v1/working-memory/{session_id}", params=params
         )
         response.raise_for_status()
         return AckResponse(**response.json())
@@ -391,7 +391,8 @@ async def create_long_term_memory(
 
         payload = CreateMemoryRecordRequest(memories=memories)
         response = await self._client.post(
-            "/long-term-memory", json=payload.model_dump(exclude_none=True, mode="json")
+            "/v1/long-term-memory/",
+            json=payload.model_dump(exclude_none=True, mode="json"),
         )
         response.raise_for_status()
         return AckResponse(**response.json())
@@ -471,7 +472,7 @@ async def search_long_term_memory(
         )
 
         response = await self._client.post(
-            "/long-term-memory/search",
+            "/v1/long-term-memory/search",
             json=payload.model_dump(exclude_none=True, mode="json"),
         )
         response.raise_for_status()
@@ -566,7 +567,7 @@ async def search_memories(
         )
 
         response = await self._client.post(
-            "/memory/search",
+            "/v1/memory/search",
             json=payload.model_dump(exclude_none=True, mode="json"),
         )
         response.raise_for_status()
@@ -638,7 +639,7 @@ async def memory_prompt(
 
         # Make the API call
         response = await self._client.post(
-            "/memory-prompt", json=payload.model_dump(exclude_none=True, mode="json")
+            "/v1/memory/prompt", json=payload.model_dump(exclude_none=True, mode="json")
         )
         response.raise_for_status()
         data = response.json()
@@ -761,7 +762,7 @@ async def hydrate_memory_prompt(
 
         # Make the API call
         response = await self._client.post(
-            "/memory-prompt", json=payload.model_dump(exclude_none=True, mode="json")
+            "/v1/memory/prompt", json=payload.model_dump(exclude_none=True, mode="json")
         )
         response.raise_for_status()
         data = response.json()

agent_memory_server/healthcheck.py

@@ -8,7 +8,7 @@
 router = APIRouter()
 
 
-@router.get("/health", response_model=HealthCheckResponse)
+@router.get("/v1/health", response_model=HealthCheckResponse)
 async def get_health():
     """
     Health check endpoint

docs/api.md

@@ -2,23 +2,23 @@
 
 The following endpoints are available:
 
-- **GET /health**
+- **GET /v1/health**
   A simple health check endpoint returning the current server time.
   Example Response:
 
   ```json
   { "now": 1616173200 }
   ```
 
-- **GET /sessions/**
+- **GET /v1/working-memory/**
   Retrieves a paginated list of session IDs.
   _Query Parameters:_
 
   - `limit` (int): Number of sessions per page (default: 10)
   - `offset` (int): Number of sessions to skip (default: 0)
   - `namespace` (string, optional): Filter sessions by namespace.
 
-- **GET /sessions/{session_id}/memory**
+- **GET /v1/working-memory/{session_id}**
   Retrieves working memory for a session, including messages, structured memories,
   context, and metadata.
   _Query Parameters:_
@@ -28,7 +28,7 @@ The following endpoints are available:
   - `model_name` (string, optional): The client's LLM model name to determine appropriate context window size
   - `context_window_max` (int, optional): Direct specification of max context window tokens (overrides model_name)
 
-- **PUT /sessions/{session_id}/memory**
+- **PUT /v1/working-memory/{session_id}**
   Sets working memory for a session, replacing any existing memory.
   Automatically summarizes conversations that exceed the window size.
   _Request Body Example:_
@@ -52,10 +52,10 @@ The following endpoints are available:
   }
   ```
 
-- **DELETE /sessions/{session_id}/memory**
+- **DELETE /v1/working-memory/{session_id}**
   Deletes all working memory (messages, context, structured memories, metadata) for a session.
 
-- **POST /long-term-memory**
+- **POST /v1/long-term-memory/**
   Creates long-term memories directly, bypassing working memory.
   _Request Body Example:_
 
@@ -73,7 +73,7 @@ The following endpoints are available:
   }
   ```
 
-- **POST /long-term-memory/search**
+- **POST /v1/long-term-memory/search**
   Performs vector search on long-term memories with advanced filtering options.
   _Request Body Example:_
 
@@ -92,7 +92,7 @@ The following endpoints are available:
   }
   ```
 
-- **POST /memory-prompt**
+- **POST /v1/memory/prompt**
   Generates prompts enriched with relevant memory context from both working
   memory and long-term memory. Useful for retrieving context before answering questions.
   _Request Body Example:_

docs/authentication.md

@@ -64,7 +64,7 @@ OAUTH2_AUDIENCE=your-application-id
 # Make authenticated API request
 curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
      -H "Content-Type: application/json" \
-     http://localhost:8000/sessions/
+     http://localhost:8000/v1/working-memory/
 
 # Python example
 import httpx
@@ -74,7 +74,7 @@ headers = {
     "Content-Type": "application/json"
 }
 
-response = httpx.get("http://localhost:8000/sessions/", headers=headers)
+response = httpx.get("http://localhost:8000/v1/working-memory/", headers=headers)
 ```
 
 ### Development Mode (Local Testing)
@@ -85,7 +85,7 @@ export DISABLE_AUTH=true
 
 # Now you can make requests without tokens
 curl -H "Content-Type: application/json" \
-     http://localhost:8000/sessions/
+     http://localhost:8000/v1/working-memory/
 ```
 
 ## Token Requirements

docs/memory-types.md

@@ -86,13 +86,13 @@ Working memory contains:
 
 ```http
 # Get working memory for a session
-GET /sessions/{session_id}/memory?namespace=demo&window_size=50
+GET /v1/working-memory/{session_id}?namespace=demo&window_size=50
 
 # Set working memory (replaces existing)
-PUT /sessions/{session_id}/memory
+PUT /v1/working-memory/{session_id}
 
 # Delete working memory
-DELETE /sessions/{session_id}/memory?namespace=demo
+DELETE /v1/working-memory/{session_id}?namespace=demo
 ```
 
 ### Automatic Promotion
@@ -200,13 +200,13 @@ Long-term memory supports three types of memories:
 
 ```http
 # Create long-term memories
-POST /long-term-memory
+POST /v1/long-term-memory/
 
 # Search long-term memories only
-POST /long-term-memory/search
+POST /v1/long-term-memory/search
 
 # Search across all memory types
-POST /memory/search
+POST /v1/memory/search
 ```
 
 ### Search Capabilities
@@ -295,7 +295,7 @@ results = await search_memories(
 
 ## Memory Prompt Integration
 
-The memory system integrates with AI prompts through the `/memory-prompt` endpoint:
+The memory system integrates with AI prompts through the `/v1/memory/prompt` endpoint:
 
 ```python
 # Get memory-enriched prompt

manual_oauth_qa/README.md

@@ -162,14 +162,14 @@ echo "Access Token: $TOKEN"
 # Test sessions endpoint
 curl -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
-     http://localhost:8000/sessions/
+     http://localhost:8000/v1/working-memory/
 
 # Test memory prompt
 curl -X POST \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"query": "What is the capital of France?", "session_id": "test-session"}' \
-     http://localhost:8000/memory-prompt
+     http://localhost:8000/v1/memory/prompt
 
 # Test long-term memory creation
 curl -X POST \
@@ -184,27 +184,27 @@ curl -X POST \
          }
        ]
      }' \
-     http://localhost:8000/long-term-memory
+     http://localhost:8000/v1/long-term-memory/
 
 # Test memory search
 curl -X POST \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"text": "Auth0 test", "limit": 5}' \
-     http://localhost:8000/long-term-memory/search
+     http://localhost:8000/v1/long-term-memory/search
 ```
 
 #### Test Authentication Rejection
 
 ```bash
 # Test without token (should return 401)
 curl -H "Content-Type: application/json" \
-     http://localhost:8000/sessions/
+     http://localhost:8000/v1/working-memory/
 
 # Test with invalid token (should return 401)
 curl -H "Authorization: Bearer invalid.jwt.token" \
      -H "Content-Type: application/json" \
-     http://localhost:8000/sessions/
+     http://localhost:8000/v1/working-memory/
 ```
 
 ### Method 3: Using Python Requests
@@ -234,7 +234,7 @@ headers = {
     "Content-Type": "application/json"
 }
 
-response = requests.get("http://localhost:8000/sessions/", headers=headers)
+response = requests.get("http://localhost:8000/v1/working-memory/", headers=headers)
 print(f"Status: {response.status_code}")
 print(f"Response: {response.json()}")
 ```