letta-nightly 0.11.7.dev20250915104130__py3-none-any.whl → 0.11.7.dev20250917104122__py3-none-any.whl

letta/server/rest_api/routers/v1/sandbox_configs.py

@@ -17,7 +17,7 @@ from letta.schemas.sandbox_config import (
     SandboxConfigCreate,
     SandboxConfigUpdate,
 )
-from letta.server.rest_api.utils import get_letta_server, get_user_id
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 from letta.services.helpers.tool_execution_helper import create_venv_for_local_sandbox, install_pip_requirements_for_sandbox
 
@@ -32,9 +32,9 @@ logger = get_logger(__name__)
 async def create_sandbox_config(
     config_create: SandboxConfigCreate,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     return await server.sandbox_config_manager.create_or_update_sandbox_config_async(config_create, actor)
 
@@ -42,18 +42,18 @@ async def create_sandbox_config(
 @router.post("/e2b/default", response_model=PydanticSandboxConfig)
 async def create_default_e2b_sandbox_config(
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.get_or_create_default_sandbox_config_async(sandbox_type=SandboxType.E2B, actor=actor)
 
 
 @router.post("/local/default", response_model=PydanticSandboxConfig)
 async def create_default_local_sandbox_config(
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.get_or_create_default_sandbox_config_async(sandbox_type=SandboxType.LOCAL, actor=actor)
 
 
@@ -61,7 +61,7 @@ async def create_default_local_sandbox_config(
 async def create_custom_local_sandbox_config(
     local_sandbox_config: LocalSandboxConfig,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Create or update a custom LocalSandboxConfig, including pip_requirements.
@@ -74,7 +74,7 @@ async def create_custom_local_sandbox_config(
         )
 
     # Retrieve the user (actor)
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # Wrap the LocalSandboxConfig into a SandboxConfigCreate
     sandbox_config_create = SandboxConfigCreate(config=local_sandbox_config)
@@ -90,9 +90,9 @@ async def update_sandbox_config(
     sandbox_config_id: str,
     config_update: SandboxConfigUpdate,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.update_sandbox_config_async(sandbox_config_id, config_update, actor)
 
 
@@ -100,9 +100,9 @@ async def update_sandbox_config(
 async def delete_sandbox_config(
     sandbox_config_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     await server.sandbox_config_manager.delete_sandbox_config_async(sandbox_config_id, actor)
 
 
@@ -112,22 +112,22 @@ async def list_sandbox_configs(
     after: Optional[str] = Query(None, description="Pagination cursor to fetch the next set of results"),
     sandbox_type: Optional[SandboxType] = Query(None, description="Filter for this specific sandbox type"),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.list_sandbox_configs_async(actor, limit=limit, after=after, sandbox_type=sandbox_type)
 
 
 @router.post("/local/recreate-venv", response_model=PydanticSandboxConfig)
 async def force_recreate_local_sandbox_venv(
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Forcefully recreate the virtual environment for the local sandbox.
     Deletes and recreates the venv, then reinstalls required dependencies.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # Retrieve the local sandbox config
     sbx_config = await server.sandbox_config_manager.get_or_create_default_sandbox_config_async(sandbox_type=SandboxType.LOCAL, actor=actor)
@@ -169,9 +169,9 @@ async def create_sandbox_env_var(
     sandbox_config_id: str,
     env_var_create: SandboxEnvironmentVariableCreate,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.create_sandbox_env_var_async(env_var_create, sandbox_config_id, actor)
 
 
@@ -180,9 +180,9 @@ async def update_sandbox_env_var(
     env_var_id: str,
     env_var_update: SandboxEnvironmentVariableUpdate,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.update_sandbox_env_var_async(env_var_id, env_var_update, actor)
 
 
@@ -190,9 +190,9 @@ async def update_sandbox_env_var(
 async def delete_sandbox_env_var(
     env_var_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     await server.sandbox_config_manager.delete_sandbox_env_var_async(env_var_id, actor)
 
 
@@ -202,7 +202,7 @@ async def list_sandbox_env_vars(
     limit: int = Query(1000, description="Number of results to return"),
     after: Optional[str] = Query(None, description="Pagination cursor to fetch the next set of results"),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str = Depends(get_user_id),
+    headers: HeaderParams = Depends(get_headers),
 ):
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.sandbox_config_manager.list_sandbox_env_vars_async(sandbox_config_id, actor, limit=limit, after=after)

letta/server/rest_api/routers/v1/sources.py

@@ -1,11 +1,10 @@
-import asyncio
 import mimetypes
 import os
 import tempfile
 from pathlib import Path
 from typing import List, Optional
 
-from fastapi import APIRouter, Depends, Header, HTTPException, Query, UploadFile
+from fastapi import APIRouter, Depends, HTTPException, Query, UploadFile
 from starlette import status
 from starlette.responses import Response
 
@@ -26,7 +25,7 @@ from letta.schemas.passage import Passage
 from letta.schemas.source import Source, SourceCreate, SourceUpdate
 from letta.schemas.source_metadata import OrganizationSourcesStats
 from letta.schemas.user import User
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 from letta.services.file_processor.embedder.openai_embedder import OpenAIEmbedder
 from letta.services.file_processor.embedder.pinecone_embedder import PineconeEmbedder
@@ -45,28 +44,28 @@ register_mime_types()
 router = APIRouter(prefix="/sources", tags=["sources"])
 
 
-@router.get("/count", response_model=int, operation_id="count_sources")
+@router.get("/count", response_model=int, operation_id="count_sources", deprecated=True)
 async def count_sources(
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Count all data sources created by a user.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.source_manager.size_async(actor=actor)
 
 
-@router.get("/{source_id}", response_model=Source, operation_id="retrieve_source")
+@router.get("/{source_id}", response_model=Source, operation_id="retrieve_source", deprecated=True)
 async def retrieve_source(
     source_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Get all sources
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     source = await server.source_manager.get_source_by_id(source_id=source_id, actor=actor)
     if not source:
@@ -74,16 +73,16 @@ async def retrieve_source(
     return source
 
 
-@router.get("/name/{source_name}", response_model=str, operation_id="get_source_id_by_name")
+@router.get("/name/{source_name}", response_model=str, operation_id="get_source_id_by_name", deprecated=True)
 async def get_source_id_by_name(
     source_name: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Get a source by name
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     source = await server.source_manager.get_source_by_name(source_name=source_name, actor=actor)
     if not source:
@@ -91,10 +90,10 @@ async def get_source_id_by_name(
     return source.id
 
 
-@router.get("/metadata", response_model=OrganizationSourcesStats, operation_id="get_sources_metadata")
+@router.get("/metadata", response_model=OrganizationSourcesStats, operation_id="get_sources_metadata", deprecated=True)
 async def get_sources_metadata(
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     include_detailed_per_source_metadata: bool = False,
 ):
     """
@@ -106,34 +105,34 @@ async def get_sources_metadata(
     - Total size of all files
     - Per-source breakdown with file details (file_name, file_size per file) if include_detailed_per_source_metadata is True
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.file_manager.get_organization_sources_metadata(
         actor=actor, include_detailed_per_source_metadata=include_detailed_per_source_metadata
     )
 
 
-@router.get("/", response_model=List[Source], operation_id="list_sources")
+@router.get("/", response_model=List[Source], operation_id="list_sources", deprecated=True)
 async def list_sources(
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all data sources created by a user.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.source_manager.list_sources(actor=actor)
 
 
-@router.post("/", response_model=Source, operation_id="create_source")
+@router.post("/", response_model=Source, operation_id="create_source", deprecated=True)
 async def create_source(
     source_create: SourceCreate,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Create a new data source.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # TODO: need to asyncify this
     if not source_create.embedding_config:
@@ -158,33 +157,33 @@ async def create_source(
     return await server.source_manager.create_source(source=source, actor=actor)
 
 
-@router.patch("/{source_id}", response_model=Source, operation_id="modify_source")
+@router.patch("/{source_id}", response_model=Source, operation_id="modify_source", deprecated=True)
 async def modify_source(
     source_id: str,
     source: SourceUpdate,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Update the name or documentation of an existing data source.
     """
     # TODO: allow updating the handle/embedding config
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     if not await server.source_manager.get_source_by_id(source_id=source_id, actor=actor):
         raise HTTPException(status_code=404, detail=f"Source with id={source_id} does not exist.")
     return await server.source_manager.update_source(source_id=source_id, source_update=source, actor=actor)
 
 
-@router.delete("/{source_id}", response_model=None, operation_id="delete_source")
+@router.delete("/{source_id}", response_model=None, operation_id="delete_source", deprecated=True)
 async def delete_source(
     source_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Delete a data source.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     source = await server.source_manager.get_source_by_id(source_id=source_id, actor=actor)
     agent_states = await server.source_manager.list_attached_agents(source_id=source_id, actor=actor)
     files = await server.file_manager.list_files(source_id, actor)
@@ -212,14 +211,14 @@ async def delete_source(
     await server.delete_source(source_id=source_id, actor=actor)
 
 
-@router.post("/{source_id}/upload", response_model=FileMetadata, operation_id="upload_file_to_source")
+@router.post("/{source_id}/upload", response_model=FileMetadata, operation_id="upload_file_to_source", deprecated=True)
 async def upload_file_to_source(
     file: UploadFile,
     source_id: str,
     duplicate_handling: DuplicateFileHandling = Query(DuplicateFileHandling.SUFFIX, description="How to handle duplicate filenames"),
     name: Optional[str] = Query(None, description="Optional custom name to override the uploaded file's name"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Upload a file to a data source.
@@ -256,7 +255,7 @@ async def upload_file_to_source(
             ),
         )
 
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     source = await server.source_manager.get_source_by_id(source_id=source_id, actor=actor)
     if source is None:
@@ -330,32 +329,32 @@ async def upload_file_to_source(
     return file_metadata
 
 
-@router.get("/{source_id}/agents", response_model=List[str], operation_id="get_agents_for_source")
+@router.get("/{source_id}/agents", response_model=List[str], operation_id="get_agents_for_source", deprecated=True)
 async def get_agents_for_source(
     source_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Get all agent IDs that have the specified source attached.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.source_manager.get_agents_for_source_id(source_id=source_id, actor=actor)
 
 
-@router.get("/{source_id}/passages", response_model=List[Passage], operation_id="list_source_passages")
+@router.get("/{source_id}/passages", response_model=List[Passage], operation_id="list_source_passages", deprecated=True)
 async def list_source_passages(
     source_id: str,
     after: Optional[str] = Query(None, description="Message after which to retrieve the returned messages."),
     before: Optional[str] = Query(None, description="Message before which to retrieve the returned messages."),
     limit: int = Query(100, description="Maximum number of messages to retrieve."),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List all passages associated with a data source.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.agent_manager.query_source_passages_async(
         actor=actor,
         source_id=source_id,
@@ -365,7 +364,7 @@ async def list_source_passages(
     )
 
 
-@router.get("/{source_id}/files", response_model=List[FileMetadata], operation_id="list_source_files")
+@router.get("/{source_id}/files", response_model=List[FileMetadata], operation_id="list_source_files", deprecated=True)
 async def list_source_files(
     source_id: str,
     limit: int = Query(1000, description="Number of files to return"),
@@ -376,12 +375,12 @@ async def list_source_files(
         description="Whether to check and update file processing status (from the vector db service). If False, will not fetch and update the status, which may lead to performance gains.",
     ),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     List paginated files associated with a data source.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
     return await server.file_manager.list_files(
         source_id=source_id,
         limit=limit,
@@ -393,18 +392,18 @@ async def list_source_files(
     )
 
 
-@router.get("/{source_id}/files/{file_id}", response_model=FileMetadata, operation_id="get_file_metadata")
+@router.get("/{source_id}/files/{file_id}", response_model=FileMetadata, operation_id="get_file_metadata", deprecated=True)
 async def get_file_metadata(
     source_id: str,
     file_id: str,
     include_content: bool = Query(False, description="Whether to include full file content"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Retrieve metadata for a specific file by its ID.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # Get file metadata using the file manager
     file_metadata = await server.file_manager.get_file_by_id(
@@ -426,17 +425,17 @@ async def get_file_metadata(
 
 # it's redundant to include /delete in the URL path. The HTTP verb DELETE already implies that action.
 # it's still good practice to return a status indicating the success or failure of the deletion
-@router.delete("/{source_id}/{file_id}", status_code=204, operation_id="delete_file_from_source")
+@router.delete("/{source_id}/{file_id}", status_code=204, operation_id="delete_file_from_source", deprecated=True)
 async def delete_file_from_source(
     source_id: str,
     file_id: str,
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
     Delete a data source.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     deleted_file = await server.file_manager.delete_file(file_id=file_id, actor=actor)
 

letta/server/rest_api/routers/v1/steps.py

@@ -8,7 +8,7 @@ from letta.orm.errors import NoResultFound
 from letta.schemas.provider_trace import ProviderTrace
 from letta.schemas.step import Step
 from letta.schemas.step_metrics import StepMetrics
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
 from letta.services.step_manager import FeedbackType
 from letta.settings import settings
@@ -21,7 +21,10 @@ async def list_steps(
     before: Optional[str] = Query(None, description="Return steps before this step ID"),
     after: Optional[str] = Query(None, description="Return steps after this step ID"),
     limit: Optional[int] = Query(50, description="Maximum number of steps to return"),
-    order: Optional[str] = Query("desc", description="Sort order (asc or desc)"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     start_date: Optional[str] = Query(None, description='Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")'),
     end_date: Optional[str] = Query(None, description='Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")'),
     model: Optional[str] = Query(None, description="Filter by the name of the model used for the step"),
@@ -32,16 +35,15 @@ async def list_steps(
     tags: Optional[list[str]] = Query(None, description="Filter by tags"),
     project_id: Optional[str] = Query(None, description="Filter by the project ID that is associated with the step (cloud only)."),
     server: SyncServer = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     x_project: Optional[str] = Header(
         None, alias="X-Project", description="Filter by project slug to associate with the group (cloud only)."
     ),  # Only handled by next js middleware
 ):
     """
     List steps with optional pagination and date filters.
-    Dates should be provided in ISO 8601 format (e.g. 2025-01-29T15:01:19-08:00)
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     # Convert ISO strings to datetime objects if provided
     start_dt = datetime.fromisoformat(start_date) if start_date else None
@@ -54,7 +56,7 @@ async def list_steps(
         start_date=start_dt,
         end_date=end_dt,
         limit=limit,
-        order=order,
+        order=(order == "asc"),
         model=model,
         agent_id=agent_id,
         trace_ids=trace_ids,
@@ -67,46 +69,46 @@ async def list_steps(
 @router.get("/{step_id}", response_model=Step, operation_id="retrieve_step")
 async def retrieve_step(
     step_id: str,
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     server: SyncServer = Depends(get_letta_server),
 ):
     """
     Get a step by ID.
     """
     try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
         return await server.step_manager.get_step_async(step_id=step_id, actor=actor)
     except NoResultFound:
         raise HTTPException(status_code=404, detail="Step not found")
 
 
-@router.get("/{step_id}/metrics", response_model=StepMetrics, operation_id="retrieve_step_metrics")
-async def retrieve_step_metrics(
+@router.get("/{step_id}/metrics", response_model=StepMetrics, operation_id="retrieve_metrics_for_step")
+async def retrieve_metrics_for_step(
     step_id: str,
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     server: SyncServer = Depends(get_letta_server),
 ):
     """
     Get step metrics by step ID.
     """
     try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
         return await server.step_manager.get_step_metrics_async(step_id=step_id, actor=actor)
     except NoResultFound:
         raise HTTPException(status_code=404, detail="Step metrics not found")
 
 
-@router.get("/{step_id}/trace", response_model=Optional[ProviderTrace], operation_id="retrieve_step_trace")
-async def retrieve_step_trace(
+@router.get("/{step_id}/trace", response_model=Optional[ProviderTrace], operation_id="retrieve_trace_for_step")
+async def retrieve_trace_for_step(
     step_id: str,
     server: SyncServer = Depends(get_letta_server),
-    actor_id: str | None = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
+    headers: HeaderParams = Depends(get_headers),
 ):
     provider_trace = None
     if settings.track_provider_trace:
         try:
             provider_trace = await server.telemetry_manager.get_provider_trace_by_step_id_async(
-                step_id=step_id, actor=await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+                step_id=step_id, actor=await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
             )
         except:
             pass
@@ -114,23 +116,23 @@ async def retrieve_step_trace(
     return provider_trace
 
 
-class AddFeedbackRequest(BaseModel):
+class ModifyFeedbackRequest(BaseModel):
     feedback: FeedbackType | None = Field(None, description="Whether this feedback is positive or negative")
     tags: list[str] | None = Field(None, description="Feedback tags to add to the step")
 
 
-@router.patch("/{step_id}/feedback", response_model=Step, operation_id="add_feedback")
-async def add_feedback(
+@router.patch("/{step_id}/feedback", response_model=Step, operation_id="modify_feedback_for_step")
+async def modify_feedback_for_step(
     step_id: str,
-    request: AddFeedbackRequest = Body(...),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    request: ModifyFeedbackRequest = Body(...),
+    headers: HeaderParams = Depends(get_headers),
     server: SyncServer = Depends(get_letta_server),
 ):
     """
-    Add feedback to a step.
+    Modify feedback for a given step.
     """
     try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
         return await server.step_manager.add_feedback_async(step_id=step_id, feedback=request.feedback, tags=request.tags, actor=actor)
     except NoResultFound:
         raise HTTPException(status_code=404, detail="Step not found")
@@ -140,13 +142,13 @@ async def add_feedback(
 async def update_step_transaction_id(
     step_id: str,
     transaction_id: str,
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
     server: SyncServer = Depends(get_letta_server),
 ):
     """
     Update the transaction ID for a step.
     """
-    actor = server.user_manager.get_user_or_default(user_id=actor_id)
+    actor = server.user_manager.get_user_or_default(user_id=headers.actor_id)
 
     try:
         return await server.step_manager.update_step_transaction_id(actor=actor, step_id=step_id, transaction_id=transaction_id)

letta/server/rest_api/routers/v1/tags.py

@@ -1,8 +1,8 @@
 from typing import TYPE_CHECKING, List, Literal, Optional
 
-from fastapi import APIRouter, Depends, Header, Query
+from fastapi import APIRouter, Depends, Query
 
-from letta.server.rest_api.utils import get_letta_server
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 
 if TYPE_CHECKING:
     from letta.server.server import SyncServer
@@ -24,15 +24,19 @@ async def list_tags(
         "asc", description="Sort order for tags. 'asc' for alphabetical order, 'desc' for reverse alphabetical order"
     ),
     order_by: Literal["name"] = Query("name", description="Field to sort by"),
-    query_text: Optional[str] = Query(None, description="Filter tags by text search"),
+    query_text: Optional[str] = Query(
+        None, description="Filter tags by text search. Deprecated, please use name field instead", deprecated=True
+    ),
+    name: Optional[str] = Query(None, description="Filter tags by name"),
     server: "SyncServer" = Depends(get_letta_server),
-    actor_id: Optional[str] = Header(None, alias="user_id"),
+    headers: HeaderParams = Depends(get_headers),
 ):
     """
-    Get a list of all agent tags in the database.
+    Get the list of all agent tags that have been created.
     """
-    actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    text_filter = name or query_text
     tags = await server.agent_manager.list_tags_async(
-        actor=actor, before=before, after=after, limit=limit, query_text=query_text, ascending=(order == "asc")
+        actor=actor, before=before, after=after, limit=limit, query_text=text_filter, ascending=(order == "asc")
     )
     return tags