Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

feat(core): add internal search cache warming (#10148)

Kian Jones61275b2aadf2
diff --git a/fern/openapi-overrides.yml b/fern/openapi-overrides.yml
new file mode 100644
index 000000000..08c9f7daf
--- /dev/null
+++ b/fern/openapi-overrides.yml
@@ -0,0 +1,1355 @@
+servers:
+ - url: https://api.letta.com
+ description: Letta Cloud
+ x-fern-server-name: Letta Cloud
+ - url: http://localhost:8283
+ description: Self-hosted
+ x-fern-server-name: Self-hosted
+
+components:
+ schemas:
+ UpdateMCPServerRequest:
+ x-fern-ignore: true
+ CreateMCPServerRequest:
+ x-fern-ignore: true
+ StdioMCPServer:
+ x-fern-ignore: true
+ SSEMCPServer:
+ x-fern-ignore: true
+ StreamableHTTPMCPServer:
+ x-fern-ignore: true
+
+paths:
+ /v1/mcp-servers/:
+ get:
+ x-fern-ignore: true
+ post:
+ x-fern-ignore: true
+ /v1/mcp-servers/{mcp_server_id}:
+ get:
+ x-fern-ignore: true
+ patch:
+ x-fern-ignore: true
+ delete:
+ x-fern-ignore: true
+ /v1/mcp-servers/{mcp_server_id}/tools:
+ get:
+ x-fern-ignore: true
+ /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}:
+ get:
+ x-fern-ignore: true
+ /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}/run:
+ post:
+ x-fern-ignore: true
+ /v1/mcp-servers/{mcp_server_id}/refresh:
+ post:
+ x-fern-ignore: true
+ patch:
+ x-fern-ignore: true
+ /v1/mcp-servers/connect/{mcp_server_id}:
+ post:
+ x-fern-ignore: true
+ /v1/tools/{tool_id}:
+ get:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: modify
+ /v1/tools/:
+ get:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: create
+ put:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: upsert
+ /v1/tools/count:
+ get:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: count
+ /v1/tools/add-base-tools:
+ post:
+ x-fern-sdk-group-name:
+ - tools
+ x-fern-sdk-method-name: upsert_base_tools
+ /v1/tools/mcp/oauth/callback/{session_id}:
+ get:
+ x-fern-ignore: true
+ /v1/tools/mcp/servers:
+ get:
+ summary: "List MCP Servers"
+ put:
+ summary: "Add MCP Server To Config"
+ /v1/tools/mcp/servers/{mcp_server_name}/tools:
+ get:
+ summary: "List MCP Tools By Server"
+ /v1/tools/mcp/servers/{mcp_server_name}/tools/{tool_name}/execute:
+ post:
+ x-fern-ignore: true
+ /v1/tools/mcp/servers/{mcp_server_name}/{mcp_tool_name}:
+ post:
+ summary: "Add MCP Tool"
+ /v1/tools/mcp/servers/{mcp_server_name}/resync:
+ post:
+ x-fern-ignore: true
+ /v1/tools/mcp/servers/{mcp_server_name}:
+ patch:
+ summary: "Update MCP Server"
+ delete:
+ summary: "Delete MCP Server From Config"
+ /v1/tools/mcp/servers/test:
+ post:
+ x-fern-availability: deprecated
+ summary: "Test MCP Server"
+ /v1/tools/mcp/servers/connect:
+ post:
+ x-fern-streaming:
+ format: sse
+ summary: "Connect MCP Server"
+ responses:
+ '200':
+ content:
+ text/event-stream:
+ schema:
+ x-fern-type-name: StreamingResponse
+ type: object
+ properties:
+ event:
+ type: string
+ enum:
+ - connection_attempt
+ - success
+ - error
+ - oauth_required
+ - authorization_url
+ - waiting_for_auth
+ message:
+ type: string
+ tools:
+ $ref: '#/components/schemas/MCPTool'
+ required:
+ - event
+ /v1/sources/{source_id}:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: modify
+ /v1/sources/name/{source_name}:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: retrieve_by_name
+ /v1/sources/:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: create
+ /v1/sources/count:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ x-fern-sdk-method-name: count
+ /v1/sources/{source_id}/upload:
+ post:
+ x-fern-sdk-group-name:
+ - sources
+ - files
+ x-fern-sdk-method-name: upload
+ /v1/sources/{source_id}/passages:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ - passages
+ x-fern-sdk-method-name: list
+ /v1/sources/{source_id}/files:
+ get:
+ x-fern-sdk-group-name:
+ - sources
+ - files
+ x-fern-sdk-method-name: list
+ /v1/sources/{source_id}/{file_id}:
+ delete:
+ x-fern-sdk-group-name:
+ - sources
+ - files
+ x-fern-sdk-method-name: delete
+ /v1/folders/{folder_id}:
+ get:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: modify
+ /v1/folders/name/{folder_name}:
+ get:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: retrieve_by_name
+ /v1/folders/:
+ get:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: create
+ /v1/folders/count:
+ get:
+ x-fern-sdk-group-name:
+ - folders
+ x-fern-sdk-method-name: count
+ /v1/folders/{folder_id}/upload:
+ post:
+ x-fern-sdk-group-name:
+ - folders
+ - files
+ x-fern-sdk-method-name: upload
+ /v1/folders/{folder_id}/passages:
+ get:
+ summary: List Passages For Folder
+ x-fern-sdk-group-name:
+ - folders
+ - passages
+ x-fern-sdk-method-name: list
+ /v1/folders/{folder_id}/files:
+ get:
+ summary: List Files For Folder
+ x-fern-sdk-group-name:
+ - folders
+ - files
+ x-fern-sdk-method-name: list
+ /v1/folders/{folder_id}/{file_id}:
+ delete:
+ x-fern-sdk-group-name:
+ - folders
+ - files
+ x-fern-sdk-method-name: delete
+ /v1/folders/{folder_id}/agents:
+ get:
+ x-fern-sdk-group-name:
+ - folders
+ - agents
+ x-fern-sdk-method-name: list
+ /v1/agents/:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: create
+ /v1/agents/{agent_id}:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: modify
+ /v1/agents/count:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: count
+ /v1/agents/search:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: search
+ summary: Search Agents
+ description: |
+ <Note>This endpoint is only available on Letta Cloud.</Note>
+
+ Search deployed agents.
+ /v1/agents/{agent_id}/context:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - context
+ x-fern-sdk-method-name: retrieve
+ /v1/agents/{agent_id}/tools:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - tools
+ x-fern-sdk-method-name: list
+ /v1/agents/{agent_id}/tools/attach/{tool_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - tools
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: tool_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/tools/detach/{tool_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - tools
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: tool_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/tools/approval/{tool_name}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - tools
+ x-fern-sdk-method-name: modify_approval
+ /v1/agents/{agent_id}/sources:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - sources
+ x-fern-sdk-method-name: list
+ /v1/agents/{agent_id}/core-memory:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - core_memory
+ x-fern-sdk-method-name: retrieve
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/core-memory/blocks:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - blocks
+ x-fern-sdk-method-name: list
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - blocks
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: block_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/core-memory/blocks/detach/{block_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - blocks
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: block_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/core-memory/blocks/{block_label}:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - blocks
+ x-fern-sdk-method-name: retrieve
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: block_label
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - blocks
+ x-fern-sdk-method-name: modify
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: block_label
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/archival-memory:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - passages
+ x-fern-sdk-method-name: list
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - passages
+ x-fern-sdk-method-name: create
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/archival-memory/{memory_id}:
+ delete:
+ x-fern-sdk-group-name:
+ - agents
+ - passages
+ x-fern-sdk-method-name: delete
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: memory_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ /v1/agents/{agent_id}/archival-memory/search:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - passages
+ x-fern-sdk-method-name: search
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/reset-messages:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: reset
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/messages:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: create
+ requestBody:
+ content:
+ application/json:
+ example:
+ messages:
+ - role: user
+ content:
+ - type: text
+ text: "The sky above the port was the color of television, tuned to a dead channel."
+ /v1/agents/{agent_id}/messages/{message_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: modify
+ /v1/agents/{agent_id}/messages/async:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: create_async
+ /v1/agents/{agent_id}/messages/stream:
+ post:
+ x-fern-streaming:
+ format: sse
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: create_stream
+ requestBody:
+ content:
+ application/json:
+ example:
+ messages:
+ - role: user
+ content:
+ - type: text
+ text: "The sky above the port was the color of television, tuned to a dead channel."
+ responses:
+ '200':
+ content:
+ text/event-stream:
+ schema:
+ x-fern-type-name: LettaStreamingResponse
+ oneOf:
+ - $ref: '#/components/schemas/SystemMessage'
+ - $ref: '#/components/schemas/UserMessage'
+ - $ref: '#/components/schemas/ReasoningMessage'
+ - $ref: '#/components/schemas/HiddenReasoningMessage'
+ - $ref: '#/components/schemas/ToolCallMessage'
+ - $ref: '#/components/schemas/ToolReturnMessage'
+ - $ref: '#/components/schemas/AssistantMessage'
+ - $ref: '#/components/schemas/ApprovalRequestMessage'
+ - $ref: '#/components/schemas/ApprovalResponseMessage'
+ - $ref: '#/components/schemas/SummaryMessage'
+ - $ref: '#/components/schemas/EventMessage'
+ - $ref: '#/components/schemas/LettaPing'
+ - $ref: '#/components/schemas/LettaErrorMessage'
+ - $ref: '#/components/schemas/LettaStopReason'
+ - $ref: '#/components/schemas/LettaUsageStatistics'
+ /v1/agents/{agent_id}/messages/cancel:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: cancel
+ /v1/agents/{agent_id}/messages/preview-raw-payload:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: preview
+ /v1/agents/messages/search:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: search
+ /v1/agents/{agent_id}/summarize:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ - messages
+ x-fern-sdk-method-name: summarize
+ /v1/agents/{agent_id}/core-memory/variables:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - memory_variables
+ x-fern-sdk-method-name: list
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ description: |
+ <Note>This endpoint is only available on Letta Cloud.</Note>
+
+ Returns the memory variables associated with an agent.
+ /v1/agents/{agent_id}/sources/attach/{source_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - sources
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: source_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/sources/detach/{source_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - sources
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: source_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/folders:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - folders
+ x-fern-sdk-method-name: list
+ /v1/agents/{agent_id}/folders/attach/{folder_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - folders
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: folder_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/folders/detach/{folder_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - folders
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: folder_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/archives/attach/{archive_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - archives
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: archive_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/archives/detach/{archive_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - archives
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: archive_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/identities/attach/{identity_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - identities
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: identity_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/identities/detach/{identity_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - identities
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: identity_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/import:
+ post:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: import_file
+ /v1/agents/{agent_id}/export:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ x-fern-sdk-method-name: export_file
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/agents/{agent_id}/groups:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - groups
+ x-fern-sdk-method-name: list
+ parameters:
+ - name: agent_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/models/:
+ get:
+ summary: List LLM Models
+ x-fern-sdk-group-name:
+ - models
+ x-fern-sdk-method-name: list
+ /v1/models/embedding:
+ get:
+ x-fern-sdk-group-name:
+ - models
+ - embeddings
+ x-fern-sdk-method-name: list
+ /v1/blocks/:
+ get:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: create
+ /v1/blocks/{block_id}:
+ get:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: modify
+ /v1/blocks/count:
+ get:
+ x-fern-sdk-group-name:
+ - blocks
+ x-fern-sdk-method-name: count
+ /v1/blocks/{block_id}/agents:
+ get:
+ x-fern-sdk-group-name:
+ - blocks
+ - agents
+ x-fern-sdk-method-name: list
+ /v1/blocks/{block_id}/identities/attach/{identity_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - blocks
+ - identities
+ x-fern-sdk-method-name: attach
+ parameters:
+ - name: block_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: identity_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/blocks/{block_id}/identities/detach/{identity_id}:
+ patch:
+ x-fern-sdk-group-name:
+ - blocks
+ - identities
+ x-fern-sdk-method-name: detach
+ parameters:
+ - name: block_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: identity_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/jobs/:
+ get:
+ x-fern-sdk-group-name:
+ - jobs
+ x-fern-sdk-method-name: list
+ /v1/jobs/active:
+ get:
+ x-fern-sdk-group-name:
+ - jobs
+ x-fern-sdk-method-name: listActive
+ /v1/jobs/{job_id}:
+ get:
+ x-fern-sdk-group-name:
+ - jobs
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - jobs
+ x-fern-sdk-method-name: delete
+ /v1/runs/:
+ get:
+ x-fern-sdk-group-name:
+ - runs
+ x-fern-sdk-method-name: list
+ /v1/runs/active:
+ get:
+ x-fern-sdk-group-name:
+ - runs
+ x-fern-sdk-method-name: list_active
+ /v1/runs/{run_id}:
+ get:
+ x-fern-sdk-group-name:
+ - runs
+ x-fern-sdk-method-name: retrieve
+ delete:
+ x-fern-sdk-group-name:
+ - runs
+ x-fern-sdk-method-name: delete
+ /v1/runs/{run_id}/messages:
+ get:
+ summary: List Messages For Run
+ x-fern-sdk-group-name:
+ - runs
+ - messages
+ x-fern-sdk-method-name: list
+ /v1/runs/{run_id}/usage:
+ get:
+ summary: Retrieve Usage For Run
+ x-fern-sdk-group-name:
+ - runs
+ - usage
+ x-fern-sdk-method-name: retrieve
+ /v1/runs/{run_id}/steps:
+ get:
+ summary: List Steps For Run
+ x-fern-sdk-group-name:
+ - runs
+ - steps
+ x-fern-sdk-method-name: list
+ /v1/runs/{run_id}/stream:
+ post:
+ x-fern-streaming:
+ format: sse
+ x-fern-sdk-group-name:
+ - runs
+ x-fern-sdk-method-name: stream
+ responses:
+ '200':
+ content:
+ text/event-stream:
+ schema:
+ $ref: '#/components/schemas/LettaStreamingResponse'
+ /v1/health/:
+ get:
+ x-fern-sdk-group-name:
+ - health
+ x-fern-sdk-method-name: check
+ /v1/templates/{project}/{template_version}/agents:
+ post:
+ x-fern-sdk-group-name:
+ - templates
+ - agents
+ x-fern-sdk-method-name: create
+ /v1/tags/:
+ get:
+ x-fern-sdk-group-name:
+ - tags
+ x-fern-sdk-method-name: list
+ /v1/providers/:
+ get:
+ x-fern-sdk-group-name:
+ - providers
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - providers
+ x-fern-sdk-method-name: create
+ /v1/providers/{provider_id}:
+ delete:
+ x-fern-sdk-group-name:
+ - providers
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ patch:
+ x-fern-sdk-group-name:
+ - providers
+ x-fern-sdk-method-name: modify
+ /v1/providers/check:
+ post:
+ x-fern-sdk-group-name:
+ - providers
+ x-fern-sdk-method-name: check
+ /v1/steps/:
+ get:
+ x-fern-sdk-group-name:
+ - steps
+ x-fern-sdk-method-name: list
+ /v1/steps/{step_id}:
+ get:
+ x-fern-sdk-group-name:
+ - steps
+ x-fern-sdk-method-name: retrieve
+ /v1/steps/{step_id}/feedback:
+ patch:
+ x-fern-sdk-group-name:
+ - steps
+ - feedback
+ x-fern-sdk-method-name: create
+ /v1/steps/{step_id}/metrics:
+ get:
+ x-fern-sdk-group-name:
+ - steps
+ - metrics
+ x-fern-sdk-method-name: retrieve
+ /v1/steps/{step_id}/trace:
+ get:
+ x-fern-sdk-group-name:
+ - steps
+ - trace
+ x-fern-sdk-method-name: retrieve
+ /v1/steps/{step_id}/messages:
+ get:
+ x-fern-sdk-group-name:
+ - steps
+ - messages
+ x-fern-sdk-method-name: list
+ /v1/identities/:
+ get:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: create
+ put:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: upsert
+ /v1/identities/{identity_id}:
+ get:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: retrieve
+ patch:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: modify
+ delete:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ /v1/identities/count:
+ get:
+ x-fern-sdk-group-name:
+ - identities
+ x-fern-sdk-method-name: count
+ /v1/identities/{identity_id}/properties:
+ put:
+ summary: Upsert Properties For Identity
+ x-fern-sdk-group-name:
+ - identities
+ - properties
+ x-fern-sdk-method-name: upsert
+ /v1/identities/{identity_id}/agents:
+ get:
+ summary: List Agents For Identity
+ x-fern-sdk-group-name:
+ - identities
+ - agents
+ x-fern-sdk-method-name: list
+ /v1/identities/{identity_id}/blocks:
+ get:
+ summary: List Blocks For Identity
+ x-fern-sdk-group-name:
+ - identities
+ - blocks
+ x-fern-sdk-method-name: list
+ /v1/groups/:
+ get:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: list
+ post:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: create
+ /v1/groups/{group_id}:
+ get:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: retrieve
+ patch:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: modify
+ delete:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: delete
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ example:
+ success: true
+ /v1/groups/count:
+ get:
+ x-fern-sdk-group-name:
+ - groups
+ x-fern-sdk-method-name: count
+ /v1/groups/{group_id}/reset-messages:
+ patch:
+ summary: Reset Messages For Group
+ x-fern-sdk-group-name:
+ - groups
+ - messages
+ x-fern-sdk-method-name: reset
+ parameters:
+ - name: group_id
+ in: path
+ required: true
+ schema:
+ type: string
+ /v1/groups/{group_id}/messages:
+ get:
+ summary: List Messages For Group
+ x-fern-sdk-group-name:
+ - groups
+ - messages
+ x-fern-sdk-method-name: list
+ post:
+ summary: Send Message To Group
+ x-fern-sdk-group-name:
+ - groups
+ - messages
+ x-fern-sdk-method-name: create
+ requestBody:
+ content:
+ application/json:
+ example:
+ messages:
+ - role: user
+ content:
+ - type: text
+ text: "The sky above the port was the color of television, tuned to a dead channel."
+ /v1/groups/{group_id}/messages/{message_id}:
+ patch:
+ summary: Modify Message For Group
+ x-fern-sdk-group-name:
+ - groups
+ - messages
+ x-fern-sdk-method-name: modify
+ /v1/groups/{group_id}/messages/stream:
+ post:
+ summary: Stream Message To Group
+ x-fern-streaming:
+ format: sse
+ x-fern-sdk-group-name:
+ - groups
+ - messages
+ x-fern-sdk-method-name: create_stream
+ requestBody:
+ content:
+ application/json:
+ example:
+ messages:
+ - role: user
+ content:
+ - type: text
+ text: "The sky above the port was the color of television, tuned to a dead channel."
+ responses:
+ '200':
+ content:
+ text/event-stream:
+ schema:
+ x-fern-type-name: LettaStreamingResponse
+ oneOf:
+ - $ref: '#/components/schemas/SystemMessage'
+ - $ref: '#/components/schemas/UserMessage'
+ - $ref: '#/components/schemas/ReasoningMessage'
+ - $ref: '#/components/schemas/ToolCallMessage'
+ - $ref: '#/components/schemas/ToolReturnMessage'
+ - $ref: '#/components/schemas/AssistantMessage'
+ - $ref: '#/components/schemas/SummaryMessage'
+ - $ref: '#/components/schemas/EventMessage'
+ - $ref: '#/components/schemas/LettaUsageStatistics'
+ /v1/messages/batches:
+ post:
+ x-fern-sdk-group-name:
+ - batches
+ x-fern-sdk-method-name: create
+ get:
+ x-fern-sdk-group-name:
+ - batches
+ x-fern-sdk-method-name: list
+ /v1/messages/batches/{batch_id}:
+ get:
+ x-fern-sdk-group-name:
+ - batches
+ x-fern-sdk-method-name: retrieve
+ /v1/messages/batches/{batch_id}/cancel:
+ patch:
+ x-fern-sdk-group-name:
+ - batches
+ x-fern-sdk-method-name: cancel
+ /v1/messages/batches/{batch_id}/messages:
+ get:
+ x-fern-sdk-group-name:
+ - batches
+ - messages
+ x-fern-sdk-method-name: list
+ /v1/chat/completions:
+ post:
+ x-fern-sdk-group-name:
+ - chat
+ - completions
+ x-fern-sdk-method-name: create
+ /v1/embeddings/total_storage_size:
+ get:
+ x-fern-ignore: true
+ /v1/voice-beta/{agent_id}/chat/completions:
+ get:
+ x-fern-ignore: true
+ /v1/_internal_templates/groups:
+ post:
+ x-fern-ignore: true
+ /v1/_internal_templates/deployment/{deployment_id}:
+ get:
+ x-fern-ignore: true
+ delete:
+ x-fern-ignore: true
+ /v1/_internal_templates/agents:
+ post:
+ x-fern-ignore: true
+ /v1/_internal_templates/blocks:
+ post:
+ x-fern-ignore: true
+ /v1/_internal_templates/blocks/batch:
+ post:
+ x-fern-ignore: true
+ /v1/_internal_runs/:
+ get:
+ x-fern-ignore: true
+ /v1/_internal_blocks/:
+ get:
+ x-fern-ignore: true
+ post:
+ x-fern-ignore: true
+ /v1/_internal_blocks/{block_id}:
+ delete:
+ x-fern-ignore: true
+ /v1/_internal_blocks/{block_id}/agents:
+ get:
+ x-fern-ignore: true
+ /v1/_internal_search/cache-warm:
+ post:
+ x-fern-ignore: true
+ /v1/_internal_agents/{agent_id}/core-memory/blocks/{block_label}:
+ patch:
+ x-fern-ignore: true
+ /v1/projects:
+ get:
+ x-fern-sdk-group-name:
+ - projects
+ x-fern-sdk-method-name: list
+ /v1/client-side-access-tokens:
+ post:
+ x-fern-sdk-group-name:
+ - client_side_access_tokens
+ x-fern-sdk-method-name: create
+ /v1/client-side-access-tokens/{token}:
+ delete:
+ x-fern-sdk-group-name:
+ - client_side_access_tokens
+ x-fern-sdk-method-name: delete
+ /v1/templates:
+ get:
+ x-fern-sdk-group-name:
+ - templates
+ x-fern-sdk-method-name: list
+ /v1/agents/{agent_id}/files/{file_id}/close:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - files
+ x-fern-sdk-method-name: close
+ /v1/agents/{agent_id}/files/{file_id}/open:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - files
+ x-fern-sdk-method-name: open
+ /v1/agents/{agent_id}/files/close-all:
+ patch:
+ x-fern-sdk-group-name:
+ - agents
+ - files
+ x-fern-sdk-method-name: close_all
+ /v1/agents/{agent_id}/files:
+ get:
+ x-fern-sdk-group-name:
+ - agents
+ - files
+ x-fern-sdk-method-name: list
diff --git a/fern/openapi.json b/fern/openapi.json
index d5e614911..96576dcf1 100644
--- a/fern/openapi.json
+++ b/fern/openapi.json
@@ -17510,7 +17510,7 @@
"post": {
"tags": ["messages"],
"summary": "Search All Messages",
- "description": "Search messages across the organization with optional agent filtering.\nReturns messages with FTS/vector ranks and total RRF score.\n\nThis is a cloud-only feature.",
+ "description": "Search messages across the organization with optional agent filtering.\nReturns messages with FTS/vector ranks and total RRF score.\n\n\nThis is a cloud-only feature.",
"operationId": "search_all_messages",
"parameters": [],
"requestBody": {
@@ -41984,6 +41984,13 @@
],
"title": "MessageRole"
},
+ "MessageSearchCacheWarmScope": {
+ "properties": {},
+ "additionalProperties": false,
+ "type": "object",
+ "title": "MessageSearchCacheWarmScope",
+ "description": "Messages currently infer scope from the authenticated actor."
+ },
"MessageSearchRequest": {
"properties": {
"query": {
@@ -45457,6 +45464,46 @@
"required": ["query"],
"title": "SearchAllMessagesRequest"
},
+ "SearchCacheWarmRequest": {
+ "properties": {
+ "collection": {
+ "type": "string",
+ "const": "messages",
+ "title": "Collection",
+ "description": "Embedded collection whose cache should be warmed."
+ },
+ "scope": {
+ "$ref": "#/components/schemas/MessageSearchCacheWarmScope",
+ "description": "Collection-specific scope. Messages currently infer organization from the authenticated actor."
+ }
+ },
+ "additionalProperties": false,
+ "type": "object",
+ "required": ["collection", "scope"],
+ "title": "SearchCacheWarmRequest",
+ "description": "Request for warming an internal search cache."
+ },
+ "SearchCacheWarmResponse": {
+ "properties": {
+ "collection": {
+ "type": "string",
+ "const": "messages",
+ "title": "Collection"
+ },
+ "status": {
+ "type": "string",
+ "title": "Status"
+ },
+ "warmed": {
+ "type": "boolean",
+ "title": "Warmed"
+ }
+ },
+ "type": "object",
+ "required": ["collection", "status", "warmed"],
+ "title": "SearchCacheWarmResponse",
+ "description": "Response for internal search cache warming."
+ },
"SkillSchema": {
"properties": {
"name": {
diff --git a/letta/helpers/tpuf_client.py b/letta/helpers/tpuf_client.py
index 76b2c1343..98a77f29a 100644
--- a/letta/helpers/tpuf_client.py
+++ b/letta/helpers/tpuf_client.py
@@ -6,7 +6,7 @@ import logging
import random
from datetime import datetime, timezone
from functools import wraps
-from typing import TYPE_CHECKING, Any, Callable, List, Optional, Tuple, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, List, Literal, Optional, Tuple, TypeVar
if TYPE_CHECKING:
from letta.schemas.tool import Tool as PydanticTool
@@ -245,6 +245,42 @@ class TurbopufferClient:
if not self.api_key:
raise ValueError("Turbopuffer API key not provided")
+ async def hint_cache_warm(self, *, collection: Literal["messages"], scope: dict[str, str]) -> dict:
+ """Fire a cache warm hint for a supported search collection.
+
+ This signals to turbopuffer that latency-sensitive queries are coming,
+ so it can warm the cache before the first search request lands.
+
+ Args:
+ collection: Search collection whose cache should be warmed
+ scope: Collection-specific namespace resolution inputs
+
+ Returns:
+ {"status": "ACCEPTED", "namespace": "...", "collection": "messages"} on success
+ """
+ from turbopuffer import AsyncTurbopuffer
+
+ namespace_name = await self._get_cache_warm_namespace_name(collection=collection, scope=scope)
+
+ try:
+ async with AsyncTurbopuffer(api_key=self.api_key, region=self.region) as client:
+ ns = client.namespace(namespace_name)
+ result = await ns.hint_cache_warm()
+ return {"status": result.status, "namespace": namespace_name, "collection": collection}
+ except Exception as e:
+ logger.error(f"Failed to warm turbopuffer cache for collection {collection} in namespace {namespace_name}: {e}")
+ raise
+
+ async def _get_cache_warm_namespace_name(self, *, collection: Literal["messages"], scope: dict[str, str]) -> str:
+ """Resolve the namespace for a supported cache-warm collection."""
+ if collection == "messages":
+ return await self._get_message_namespace_name(scope["organization_id"])
+
+ raise LettaInvalidArgumentError(
+ f"Unsupported cache warm collection: {collection}",
+ argument_name="collection",
+ )
+
@trace_method
async def _generate_embeddings(self, texts: List[str], actor: "PydanticUser") -> List[List[float]]:
"""Generate embeddings using the default embedding configuration.
diff --git a/letta/server/rest_api/routers/v1/__init__.py b/letta/server/rest_api/routers/v1/__init__.py
index f7293eb2e..f22015bce 100644
--- a/letta/server/rest_api/routers/v1/__init__.py
+++ b/letta/server/rest_api/routers/v1/__init__.py
@@ -13,6 +13,7 @@ from letta.server.rest_api.routers.v1.identities import router as identities_rou
from letta.server.rest_api.routers.v1.internal_agents import router as internal_agents_router
from letta.server.rest_api.routers.v1.internal_blocks import router as internal_blocks_router
from letta.server.rest_api.routers.v1.internal_runs import router as internal_runs_router
+from letta.server.rest_api.routers.v1.internal_search import router as internal_search_router
from letta.server.rest_api.routers.v1.internal_templates import router as internal_templates_router
from letta.server.rest_api.routers.v1.jobs import router as jobs_router
from letta.server.rest_api.routers.v1.llms import router as llm_router
@@ -45,6 +46,7 @@ ROUTERS = [
identities_router,
internal_agents_router,
internal_blocks_router,
+ internal_search_router,
internal_runs_router,
internal_templates_router,
llm_router,
diff --git a/letta/server/rest_api/routers/v1/internal_search.py b/letta/server/rest_api/routers/v1/internal_search.py
new file mode 100644
index 000000000..47470a6d7
--- /dev/null
+++ b/letta/server/rest_api/routers/v1/internal_search.py
@@ -0,0 +1,77 @@
+from typing import Any, Literal
+
+from fastapi import APIRouter, Body, Depends
+from pydantic import BaseModel, ConfigDict, Field
+
+from letta.errors import LettaInvalidArgumentError
+from letta.helpers.tpuf_client import TurbopufferClient, should_use_tpuf_for_messages
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
+from letta.server.server import SyncServer
+
+router = APIRouter(prefix="/_internal_search", tags=["_internal_search"])
+
+
+class MessageSearchCacheWarmScope(BaseModel):
+ """Messages currently infer scope from the authenticated actor."""
+
+ model_config = ConfigDict(extra="forbid")
+
+
+class SearchCacheWarmRequest(BaseModel):
+ """Request for warming an internal search cache."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ collection: Literal["messages"] = Field(description="Embedded collection whose cache should be warmed.")
+ scope: MessageSearchCacheWarmScope = Field(
+ description="Collection-specific scope. Messages currently infer organization from the authenticated actor.",
+ )
+
+
+class SearchCacheWarmResponse(BaseModel):
+ """Response for internal search cache warming."""
+
+ collection: Literal["messages"]
+ status: str
+ warmed: bool
+
+
+_COLLECTION_FEATURE_CHECKS = {
+ "messages": should_use_tpuf_for_messages,
+}
+
+_COLLECTION_ERROR_MESSAGES = {
+ "messages": "Message cache warming requires message embedding, OpenAI, and Turbopuffer to be enabled.",
+}
+
+
+def _resolve_cache_warm_scope(request: SearchCacheWarmRequest, actor: Any) -> dict[str, str]:
+ if request.collection == "messages":
+ return {"organization_id": actor.organization_id}
+
+ raise LettaInvalidArgumentError(
+ f"Unsupported cache warm collection: {request.collection}",
+ argument_name="collection",
+ )
+
+
[email protected]("/cache-warm", response_model=SearchCacheWarmResponse, status_code=202, operation_id="warm_internal_search_cache")
+async def warm_search_cache(
+ request: SearchCacheWarmRequest = Body(...),
+ server: SyncServer = Depends(get_letta_server),
+ headers: HeaderParams = Depends(get_headers),
+):
+ """Warm the cache for a supported internal search collection."""
+ if not _COLLECTION_FEATURE_CHECKS[request.collection]():
+ raise LettaInvalidArgumentError(
+ _COLLECTION_ERROR_MESSAGES[request.collection],
+ argument_name="collection",
+ )
+
+ actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+ result = await TurbopufferClient().hint_cache_warm(
+ collection=request.collection,
+ scope=_resolve_cache_warm_scope(request, actor),
+ )
+
+ return SearchCacheWarmResponse(collection=request.collection, status=result["status"], warmed=True)
diff --git a/letta/server/rest_api/routers/v1/messages.py b/letta/server/rest_api/routers/v1/messages.py
index 748382b4c..a108b8418 100644
--- a/letta/server/rest_api/routers/v1/messages.py
+++ b/letta/server/rest_api/routers/v1/messages.py
@@ -42,7 +42,9 @@ async def list_all_messages(
"desc", description="Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"
),
conversation_id: Optional[str] = Query(None, description="Conversation ID to filter messages by"),
- include_return_message_types: Optional[List[MessageType]] = Query(None, description="Message types to include in response. When null, all message types are returned."),
+ include_return_message_types: Optional[List[MessageType]] = Query(
+ None, description="Message types to include in response. When null, all message types are returned."
+ ),
):
"""
List messages across all agents for the current user.
@@ -70,6 +72,7 @@ async def search_all_messages(
Search messages across the organization with optional agent filtering.
Returns messages with FTS/vector ranks and total RRF score.
+
This is a cloud-only feature.
"""
actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)