README.md•43.5 kB
# openapi-mcp-server
Model Context Protocol (MCP) server for Letta API.
## Description
This server provides a Model Context Protocol (MCP) interface to the API.
## Installation
1. Install dependencies:
```bash
npm install
```
2. Create a `.env` file based on `.env.example`:
```bash
cp .env.example .env
```
3. Edit the `.env` file to add your API configuration and authorization details.
## Configuration
The following environment variables can be configured in the `.env` file:
- `API_BASE_URL`: Base URL for the API (required)
- `SERVER_NAME`: Name of the MCP server (default: "openapi-mcp-server")
- `SERVER_VERSION`: Version of the MCP server (default: "1.0.0")
- `DEBUG`: Enable debug logging (true/false) (default: false)
## Usage
### Running the Server
The server is provided as both JavaScript and TypeScript versions:
```bash
# Run JavaScript version
npm start
# Or run TypeScript version (compiles on the fly)
npm run start:ts
```
### Building the TypeScript Version
```bash
npm run build
cd dist
node server.js
```
## Using as an MCP Tool Provider
This server implements the Model Context Protocol (MCP) and can be used with any MCP-compatible consumer, like Claude.js client or other MCP consumers.
Example of connecting to this server from a Claude.js client:
```javascript
import { MCP } from "claude-js";
import { createStdio } from "claude-js/mcp";
// Create stdin/stdout transport
const transport = createStdio({ command: "node path/to/server.js" });
// Connect to the MCP server
const mcp = new MCP({ transport });
await mcp.connect();
// List available tools
const { tools } = await mcp.listTools();
console.log("Available tools:", tools);
// Call a tool
const result = await mcp.callTool({
id: "TOOL-ID",
arguments: { param1: "value1" }
});
console.log("Tool result:", result);
```
## Available Tools
This MCP server provides the following tools:
### delete_tool
- **ID**: `DELETE-v1-tools-tool-id`
- **Description**: Delete a tool by name
- **Method**: `DELETE`
- **Path**: `/v1/tools/{tool_id}`
**Parameters**:
- `tool_id`: tool_id parameter (required)
- `user_id`: user_id parameter
### retrieve_tool
- **ID**: `GET-v1-tools-tool-id`
- **Description**: Get a tool by ID
- **Method**: `GET`
- **Path**: `/v1/tools/{tool_id}`
**Parameters**:
- `tool_id`: tool_id parameter (required)
- `user_id`: user_id parameter
### modify_tool
- **ID**: `PATCH-v1-tools-tool-id`
- **Description**: Update an existing tool
- **Method**: `PATCH`
- **Path**: `/v1/tools/{tool_id}`
**Parameters**:
- `tool_id`: tool_id parameter (required)
- `user_id`: user_id parameter
### list_tools
- **ID**: `GET-v1-tools-`
- **Description**: Get a list of all tools available to agents belonging to the org of the user
- **Method**: `GET`
- **Path**: `/v1/tools/`
**Parameters**:
- `after`: after parameter
- `limit`: limit parameter
- `name`: name parameter
- `user_id`: user_id parameter
### create_tool
- **ID**: `POST-v1-tools-`
- **Description**: Create a new tool
- **Method**: `POST`
- **Path**: `/v1/tools/`
**Parameters**:
- `user_id`: user_id parameter
### upsert_tool
- **ID**: `PUT-v1-tools-`
- **Description**: Create or update a tool
- **Method**: `PUT`
- **Path**: `/v1/tools/`
**Parameters**:
- `user_id`: user_id parameter
### add_base_tools
- **ID**: `POST-v1-tools-add-base-tools`
- **Description**: Upsert base tools
- **Method**: `POST`
- **Path**: `/v1/tools/add-base-tools`
**Parameters**:
- `user_id`: user_id parameter
### run_tool_from_source
- **ID**: `POST-v1-tools-run`
- **Description**: Attempt to build a tool from source, then run it on the provided arguments
- **Method**: `POST`
- **Path**: `/v1/tools/run`
**Parameters**:
- `user_id`: user_id parameter
### list_composio_apps
- **ID**: `GET-v1-tools-composio-apps`
- **Description**: Get a list of all Composio apps
- **Method**: `GET`
- **Path**: `/v1/tools/composio/apps`
**Parameters**:
- `user-id`: user-id parameter
### list_composio_actions_by_app
- **ID**: `GET-v1-tools-composio-apps-composio-app-name-actions`
- **Description**: Get a list of all Composio actions for a specific app
- **Method**: `GET`
- **Path**: `/v1/tools/composio/apps/{composio_app_name}/actions`
**Parameters**:
- `composio_app_name`: composio_app_name parameter (required)
- `user_id`: user_id parameter
### add_composio_tool
- **ID**: `POST-v1-tools-composio-composio-action-name`
- **Description**: Add a new Composio tool by action name (Composio refers to each tool as an `Action`)
- **Method**: `POST`
- **Path**: `/v1/tools/composio/{composio_action_name}`
**Parameters**:
- `composio_action_name`: composio_action_name parameter (required)
- `user_id`: user_id parameter
### list_mcp_servers
- **ID**: `GET-v1-tools-mcp-servers`
- **Description**: Get a list of all configured MCP servers
- **Method**: `GET`
- **Path**: `/v1/tools/mcp/servers`
**Parameters**:
- `user-id`: user-id parameter
### add_mcp_server
- **ID**: `PUT-v1-tools-mcp-servers`
- **Description**: Add a new MCP server to the Letta MCP server config
- **Method**: `PUT`
- **Path**: `/v1/tools/mcp/servers`
**Parameters**:
- `user_id`: user_id parameter
### list_mcp_tools_by_server
- **ID**: `GET-v1-tools-mcp-servers-mcp-server-name-tools`
- **Description**: Get a list of all tools for a specific MCP server
- **Method**: `GET`
- **Path**: `/v1/tools/mcp/servers/{mcp_server_name}/tools`
**Parameters**:
- `mcp_server_name`: mcp_server_name parameter (required)
- `user_id`: user_id parameter
### add_mcp_tool
- **ID**: `POST-v1-tools-mcp-servers-mcp-server-name-mcp-tool-name`
- **Description**: Register a new MCP tool as a Letta server by MCP server + tool name
- **Method**: `POST`
- **Path**: `/v1/tools/mcp/servers/{mcp_server_name}/{mcp_tool_name}`
**Parameters**:
- `mcp_server_name`: mcp_server_name parameter (required)
- `mcp_tool_name`: mcp_tool_name parameter (required)
- `user_id`: user_id parameter
### delete_mcp_server
- **ID**: `DELETE-v1-tools-mcp-servers-mcp-server-name`
- **Description**: Add a new MCP server to the Letta MCP server config
- **Method**: `DELETE`
- **Path**: `/v1/tools/mcp/servers/{mcp_server_name}`
**Parameters**:
- `mcp_server_name`: mcp_server_name parameter (required)
- `user_id`: user_id parameter
### retrieve_source
- **ID**: `GET-v1-sources-source-id`
- **Description**: Get all sources
- **Method**: `GET`
- **Path**: `/v1/sources/{source_id}`
**Parameters**:
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### modify_source
- **ID**: `PATCH-v1-sources-source-id`
- **Description**: Update the name or documentation of an existing data source.
- **Method**: `PATCH`
- **Path**: `/v1/sources/{source_id}`
**Parameters**:
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### delete_source
- **ID**: `DELETE-v1-sources-source-id`
- **Description**: Delete a data source.
- **Method**: `DELETE`
- **Path**: `/v1/sources/{source_id}`
**Parameters**:
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### get_source_id_by_name
- **ID**: `GET-v1-sources-name-source-name`
- **Description**: Get a source by name
- **Method**: `GET`
- **Path**: `/v1/sources/name/{source_name}`
**Parameters**:
- `source_name`: source_name parameter (required)
- `user_id`: user_id parameter
### list_sources
- **ID**: `GET-v1-sources-`
- **Description**: List all data sources created by a user.
- **Method**: `GET`
- **Path**: `/v1/sources/`
**Parameters**:
- `user_id`: user_id parameter
### create_source
- **ID**: `POST-v1-sources-`
- **Description**: Create a new data source.
- **Method**: `POST`
- **Path**: `/v1/sources/`
**Parameters**:
- `user_id`: user_id parameter
### upload_file_to_source
- **ID**: `POST-v1-sources-source-id-upload`
- **Description**: Upload a file to a data source.
- **Method**: `POST`
- **Path**: `/v1/sources/{source_id}/upload`
**Parameters**:
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### list_source_passages
- **ID**: `GET-v1-sources-source-id-passages`
- **Description**: List all passages associated with a data source.
- **Method**: `GET`
- **Path**: `/v1/sources/{source_id}/passages`
**Parameters**:
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### list_source_files
- **ID**: `GET-v1-sources-source-id-files`
- **Description**: List paginated files associated with a data source.
- **Method**: `GET`
- **Path**: `/v1/sources/{source_id}/files`
**Parameters**:
- `source_id`: source_id parameter (required)
- `limit`: Number of files to return
- `after`: Pagination cursor to fetch the next set of results
- `user_id`: user_id parameter
### delete_file_from_source
- **ID**: `DELETE-v1-sources-source-id-file-id`
- **Description**: Delete a data source.
- **Method**: `DELETE`
- **Path**: `/v1/sources/{source_id}/{file_id}`
**Parameters**:
- `source_id`: source_id parameter (required)
- `file_id`: file_id parameter (required)
- `user_id`: user_id parameter
### list_agents
- **ID**: `GET-v1-agents-`
- **Description**: List all agents associated with a given user.
This endpoint retrieves a list of all agents and their configurations
associated with the specified user ID.
- **Method**: `GET`
- **Path**: `/v1/agents/`
**Parameters**:
- `name`: Name of the agent
- `tags`: List of tags to filter agents by
- `match_all_tags`: If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.
- `before`: Cursor for pagination
- `after`: Cursor for pagination
- `limit`: Limit for pagination
- `query_text`: Search agents by name
- `project_id`: Search agents by project ID
- `template_id`: Search agents by template ID
- `base_template_id`: Search agents by base template ID
- `identity_id`: Search agents by identity ID
- `identifier_keys`: Search agents by identifier keys
- `include_relationships`: Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. If not provided, all relationships are loaded by default. Using this can optimize performance by reducing unnecessary joins.
- `ascending`: Whether to sort agents oldest to newest (True) or newest to oldest (False, default)
- `user_id`: user_id parameter
### create_agent
- **ID**: `POST-v1-agents-`
- **Description**: Create a new agent with the specified configuration.
- **Method**: `POST`
- **Path**: `/v1/agents/`
**Parameters**:
- `user_id`: user_id parameter
- `X-Project`: X-Project parameter
### export_agent_serialized
- **ID**: `GET-v1-agents-agent-id-export`
- **Description**: Export the serialized JSON representation of an agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/export`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### import_agent_serialized
- **ID**: `POST-v1-agents-import`
- **Description**: Import a serialized agent file and recreate the agent in the system.
- **Method**: `POST`
- **Path**: `/v1/agents/import`
**Parameters**:
- `append_copy_suffix`: If set to True, appends "_copy" to the end of the agent name.
- `override_existing_tools`: If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Note that Letta core tools can never be updated externally.
- `project_id`: The project ID to associate the uploaded agent with.
- `user_id`: user_id parameter
### retrieve_agent_context_window
- **ID**: `GET-v1-agents-agent-id-context`
- **Description**: Retrieve the context window of a specific agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/context`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### modify_agent
- **ID**: `PATCH-v1-agents-agent-id`
- **Description**: Update an existing agent
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### retrieve_agent
- **ID**: `GET-v1-agents-agent-id`
- **Description**: Get the state of the agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### delete_agent
- **ID**: `DELETE-v1-agents-agent-id`
- **Description**: Delete an agent.
- **Method**: `DELETE`
- **Path**: `/v1/agents/{agent_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### list_agent_tools
- **ID**: `GET-v1-agents-agent-id-tools`
- **Description**: Get tools from an existing agent
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/tools`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### attach_tool
- **ID**: `PATCH-v1-agents-agent-id-tools-attach-tool-id`
- **Description**: Attach a tool to an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/tools/attach/{tool_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `tool_id`: tool_id parameter (required)
- `user_id`: user_id parameter
### detach_tool
- **ID**: `PATCH-v1-agents-agent-id-tools-detach-tool-id`
- **Description**: Detach a tool from an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/tools/detach/{tool_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `tool_id`: tool_id parameter (required)
- `user_id`: user_id parameter
### attach_source_to_agent
- **ID**: `PATCH-v1-agents-agent-id-sources-attach-source-id`
- **Description**: Attach a source to an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/sources/attach/{source_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### detach_source_from_agent
- **ID**: `PATCH-v1-agents-agent-id-sources-detach-source-id`
- **Description**: Detach a source from an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/sources/detach/{source_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `source_id`: source_id parameter (required)
- `user_id`: user_id parameter
### list_agent_sources
- **ID**: `GET-v1-agents-agent-id-sources`
- **Description**: Get the sources associated with an agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/sources`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### retrieve_agent_memory
- **ID**: `GET-v1-agents-agent-id-core-memory`
- **Description**: Retrieve the memory state of a specific agent.
This endpoint fetches the current memory state of the agent identified by the user ID and agent ID.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/core-memory`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### retrieve_core_memory_block
- **ID**: `GET-v1-agents-agent-id-core-memory-blocks-block-label`
- **Description**: Retrieve a core memory block from an agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/core-memory/blocks/{block_label}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `block_label`: block_label parameter (required)
- `user_id`: user_id parameter
### modify_core_memory_block
- **ID**: `PATCH-v1-agents-agent-id-core-memory-blocks-block-label`
- **Description**: Updates a core memory block of an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/core-memory/blocks/{block_label}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `block_label`: block_label parameter (required)
- `user_id`: user_id parameter
### list_core_memory_blocks
- **ID**: `GET-v1-agents-agent-id-core-memory-blocks`
- **Description**: Retrieve the core memory blocks of a specific agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/core-memory/blocks`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### attach_core_memory_block
- **ID**: `PATCH-v1-agents-agent-id-core-memory-blocks-attach-block-id`
- **Description**: Attach a core memoryblock to an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### detach_core_memory_block
- **ID**: `PATCH-v1-agents-agent-id-core-memory-blocks-detach-block-id`
- **Description**: Detach a core memory block from an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/core-memory/blocks/detach/{block_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### list_passages
- **ID**: `GET-v1-agents-agent-id-archival-memory`
- **Description**: Retrieve the memories in an agent's archival memory store (paginated query).
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/archival-memory`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `after`: Unique ID of the memory to start the query range at.
- `before`: Unique ID of the memory to end the query range at.
- `limit`: How many results to include in the response.
- `search`: Search passages by text
- `ascending`: Whether to sort passages oldest to newest (True, default) or newest to oldest (False)
- `user_id`: user_id parameter
### create_passage
- **ID**: `POST-v1-agents-agent-id-archival-memory`
- **Description**: Insert a memory into an agent's archival memory store.
- **Method**: `POST`
- **Path**: `/v1/agents/{agent_id}/archival-memory`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### modify_passage
- **ID**: `PATCH-v1-agents-agent-id-archival-memory-memory-id`
- **Description**: Modify a memory in the agent's archival memory store.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/archival-memory/{memory_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `memory_id`: memory_id parameter (required)
- `user_id`: user_id parameter
### delete_passage
- **ID**: `DELETE-v1-agents-agent-id-archival-memory-memory-id`
- **Description**: Delete a memory from an agent's archival memory store.
- **Method**: `DELETE`
- **Path**: `/v1/agents/{agent_id}/archival-memory/{memory_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `memory_id`: memory_id parameter (required)
- `user_id`: user_id parameter
### list_messages
- **ID**: `GET-v1-agents-agent-id-messages`
- **Description**: Retrieve message history for an agent.
- **Method**: `GET`
- **Path**: `/v1/agents/{agent_id}/messages`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `after`: Message after which to retrieve the returned messages.
- `before`: Message before which to retrieve the returned messages.
- `limit`: Maximum number of messages to retrieve.
- `use_assistant_message`: Whether to use assistant messages
- `assistant_message_tool_name`: The name of the designated message tool.
- `assistant_message_tool_kwarg`: The name of the message argument.
- `user_id`: user_id parameter
### send_message
- **ID**: `POST-v1-agents-agent-id-messages`
- **Description**: Process a user message and return the agent's response.
This endpoint accepts a message from a user and processes it through the agent.
- **Method**: `POST`
- **Path**: `/v1/agents/{agent_id}/messages`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### modify_message
- **ID**: `PATCH-v1-agents-agent-id-messages-message-id`
- **Description**: Update the details of a message associated with an agent.
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/messages/{message_id}`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `message_id`: message_id parameter (required)
- `user_id`: user_id parameter
### create_agent_message_stream
- **ID**: `POST-v1-agents-agent-id-messages-stream`
- **Description**: Process a user message and return the agent's response.
This endpoint accepts a message from a user and processes it through the agent.
It will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True.
- **Method**: `POST`
- **Path**: `/v1/agents/{agent_id}/messages/stream`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### create_agent_message_async
- **ID**: `POST-v1-agents-agent-id-messages-async`
- **Description**: Asynchronously process a user message and return a run object.
The actual processing happens in the background, and the status can be checked using the run ID.
- **Method**: `POST`
- **Path**: `/v1/agents/{agent_id}/messages/async`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### reset_messages
- **ID**: `PATCH-v1-agents-agent-id-reset-messages`
- **Description**: Resets the messages for an agent
- **Method**: `PATCH`
- **Path**: `/v1/agents/{agent_id}/reset-messages`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `add_default_initial_messages`: If true, adds the default initial messages after resetting.
- `user_id`: user_id parameter
### create_group
- **ID**: `POST-v1-groups-`
- **Description**: Create a new multi-agent group with the specified configuration.
- **Method**: `POST`
- **Path**: `/v1/groups/`
**Parameters**:
- `user_id`: user_id parameter
- `X-Project`: X-Project parameter
### list_groups
- **ID**: `GET-v1-groups-`
- **Description**: Fetch all multi-agent groups matching query.
- **Method**: `GET`
- **Path**: `/v1/groups/`
**Parameters**:
- `manager_type`: Search groups by manager type
- `before`: Cursor for pagination
- `after`: Cursor for pagination
- `limit`: Limit for pagination
- `project_id`: Search groups by project id
- `user_id`: user_id parameter
### upsert_group
- **ID**: `PUT-v1-groups-`
- **Description**: Create a new multi-agent group with the specified configuration.
- **Method**: `PUT`
- **Path**: `/v1/groups/`
**Parameters**:
- `user_id`: user_id parameter
- `X-Project`: X-Project parameter
### delete_group
- **ID**: `DELETE-v1-groups-group-id`
- **Description**: Delete a multi-agent group.
- **Method**: `DELETE`
- **Path**: `/v1/groups/{group_id}`
**Parameters**:
- `group_id`: group_id parameter (required)
- `user_id`: user_id parameter
### send_group_message
- **ID**: `POST-v1-groups-group-id-messages`
- **Description**: Process a user message and return the group's response.
This endpoint accepts a message from a user and processes it through through agents in the group based on the specified pattern
- **Method**: `POST`
- **Path**: `/v1/groups/{group_id}/messages`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user_id`: user_id parameter
### list_group_messages
- **ID**: `GET-v1-groups-group-id-messages`
- **Description**: Retrieve message history for an agent.
- **Method**: `GET`
- **Path**: `/v1/groups/{group_id}/messages`
**Parameters**:
- `group_id`: group_id parameter (required)
- `after`: Message after which to retrieve the returned messages.
- `before`: Message before which to retrieve the returned messages.
- `limit`: Maximum number of messages to retrieve.
- `use_assistant_message`: Whether to use assistant messages
- `assistant_message_tool_name`: The name of the designated message tool.
- `assistant_message_tool_kwarg`: The name of the message argument.
- `user_id`: user_id parameter
### send_group_message_streaming
- **ID**: `POST-v1-groups-group-id-messages-stream`
- **Description**: Process a user message and return the group's responses.
This endpoint accepts a message from a user and processes it through agents in the group based on the specified pattern.
It will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True.
- **Method**: `POST`
- **Path**: `/v1/groups/{group_id}/messages/stream`
**Parameters**:
- `group_id`: group_id parameter (required)
- `user_id`: user_id parameter
### list_identities
- **ID**: `GET-v1-identities-`
- **Description**: Get a list of all identities in the database
- **Method**: `GET`
- **Path**: `/v1/identities/`
**Parameters**:
- `name`: name parameter
- `project_id`: project_id parameter
- `identifier_key`: identifier_key parameter
- `identity_type`: identity_type parameter
- `before`: before parameter
- `after`: after parameter
- `limit`: limit parameter
- `user_id`: user_id parameter
### create_identity
- **ID**: `POST-v1-identities-`
- **Description**: Make a POST request to /v1/identities/
- **Method**: `POST`
- **Path**: `/v1/identities/`
**Parameters**:
- `user_id`: user_id parameter
- `X-Project`: X-Project parameter
### upsert_identity
- **ID**: `PUT-v1-identities-`
- **Description**: Make a PUT request to /v1/identities/
- **Method**: `PUT`
- **Path**: `/v1/identities/`
**Parameters**:
- `user_id`: user_id parameter
- `X-Project`: X-Project parameter
### retrieve_identity
- **ID**: `GET-v1-identities-identity-id`
- **Description**: Make a GET request to /v1/identities/{identity_id}
- **Method**: `GET`
- **Path**: `/v1/identities/{identity_id}`
**Parameters**:
- `identity_id`: identity_id parameter (required)
- `user_id`: user_id parameter
### update_identity
- **ID**: `PATCH-v1-identities-identity-id`
- **Description**: Make a PATCH request to /v1/identities/{identity_id}
- **Method**: `PATCH`
- **Path**: `/v1/identities/{identity_id}`
**Parameters**:
- `identity_id`: identity_id parameter (required)
- `user_id`: user_id parameter
### delete_identity
- **ID**: `DELETE-v1-identities-identity-id`
- **Description**: Delete an identity by its identifier key
- **Method**: `DELETE`
- **Path**: `/v1/identities/{identity_id}`
**Parameters**:
- `identity_id`: identity_id parameter (required)
- `user_id`: user_id parameter
### list_models
- **ID**: `GET-v1-models-`
- **Description**: Make a GET request to /v1/models/
- **Method**: `GET`
- **Path**: `/v1/models/`
No parameters required.
### list_embedding_models
- **ID**: `GET-v1-models-embedding`
- **Description**: Make a GET request to /v1/models/embedding
- **Method**: `GET`
- **Path**: `/v1/models/embedding`
No parameters required.
### list_blocks
- **ID**: `GET-v1-blocks-`
- **Description**: Make a GET request to /v1/blocks/
- **Method**: `GET`
- **Path**: `/v1/blocks/`
**Parameters**:
- `label`: Labels to include (e.g. human, persona)
- `templates_only`: Whether to include only templates
- `name`: Name of the block
- `identity_id`: Search agents by identifier id
- `identifier_keys`: Search agents by identifier keys
- `user_id`: user_id parameter
### create_block
- **ID**: `POST-v1-blocks-`
- **Description**: Make a POST request to /v1/blocks/
- **Method**: `POST`
- **Path**: `/v1/blocks/`
**Parameters**:
- `user_id`: user_id parameter
### modify_block
- **ID**: `PATCH-v1-blocks-block-id`
- **Description**: Make a PATCH request to /v1/blocks/{block_id}
- **Method**: `PATCH`
- **Path**: `/v1/blocks/{block_id}`
**Parameters**:
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### delete_block
- **ID**: `DELETE-v1-blocks-block-id`
- **Description**: Make a DELETE request to /v1/blocks/{block_id}
- **Method**: `DELETE`
- **Path**: `/v1/blocks/{block_id}`
**Parameters**:
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### retrieve_block
- **ID**: `GET-v1-blocks-block-id`
- **Description**: Make a GET request to /v1/blocks/{block_id}
- **Method**: `GET`
- **Path**: `/v1/blocks/{block_id}`
**Parameters**:
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### list_agents_for_block
- **ID**: `GET-v1-blocks-block-id-agents`
- **Description**: Retrieves all agents associated with the specified block.
Raises a 404 if the block does not exist.
- **Method**: `GET`
- **Path**: `/v1/blocks/{block_id}/agents`
**Parameters**:
- `block_id`: block_id parameter (required)
- `user_id`: user_id parameter
### list_jobs
- **ID**: `GET-v1-jobs-`
- **Description**: List all jobs.
- **Method**: `GET`
- **Path**: `/v1/jobs/`
**Parameters**:
- `source_id`: Only list jobs associated with the source.
- `user_id`: user_id parameter
### list_active_jobs
- **ID**: `GET-v1-jobs-active`
- **Description**: List all active jobs.
- **Method**: `GET`
- **Path**: `/v1/jobs/active`
**Parameters**:
- `user_id`: user_id parameter
### retrieve_job
- **ID**: `GET-v1-jobs-job-id`
- **Description**: Get the status of a job.
- **Method**: `GET`
- **Path**: `/v1/jobs/{job_id}`
**Parameters**:
- `job_id`: job_id parameter (required)
- `user_id`: user_id parameter
### delete_job
- **ID**: `DELETE-v1-jobs-job-id`
- **Description**: Delete a job by its job_id.
- **Method**: `DELETE`
- **Path**: `/v1/jobs/{job_id}`
**Parameters**:
- `job_id`: job_id parameter (required)
- `user_id`: user_id parameter
### health_check
- **ID**: `GET-v1-health-`
- **Description**: Make a GET request to /v1/health/
- **Method**: `GET`
- **Path**: `/v1/health/`
No parameters required.
### create_sandbox_config_v1_sandbox_config__post
- **ID**: `POST-v1-sandbox-config-`
- **Description**: Make a POST request to /v1/sandbox-config/
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/`
**Parameters**:
- `user-id`: user-id parameter
### list_sandbox_configs_v1_sandbox_config__get
- **ID**: `GET-v1-sandbox-config-`
- **Description**: Make a GET request to /v1/sandbox-config/
- **Method**: `GET`
- **Path**: `/v1/sandbox-config/`
**Parameters**:
- `limit`: Number of results to return
- `after`: Pagination cursor to fetch the next set of results
- `sandbox_type`: Filter for this specific sandbox type
- `user-id`: user-id parameter
### create_default_e2b_sandbox_config_v1_sandbox_config_e2b_default_post
- **ID**: `POST-v1-sandbox-config-e2b-default`
- **Description**: Make a POST request to /v1/sandbox-config/e2b/default
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/e2b/default`
**Parameters**:
- `user-id`: user-id parameter
### create_default_local_sandbox_config_v1_sandbox_config_local_default_post
- **ID**: `POST-v1-sandbox-config-local-default`
- **Description**: Make a POST request to /v1/sandbox-config/local/default
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/local/default`
**Parameters**:
- `user-id`: user-id parameter
### create_custom_local_sandbox_config_v1_sandbox_config_local_post
- **ID**: `POST-v1-sandbox-config-local`
- **Description**: Create or update a custom LocalSandboxConfig, including pip_requirements.
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/local`
**Parameters**:
- `user-id`: user-id parameter
### update_sandbox_config_v1_sandbox_config__sandbox_config_id__patch
- **ID**: `PATCH-v1-sandbox-config-sandbox-config-id`
- **Description**: Make a PATCH request to /v1/sandbox-config/{sandbox_config_id}
- **Method**: `PATCH`
- **Path**: `/v1/sandbox-config/{sandbox_config_id}`
**Parameters**:
- `sandbox_config_id`: sandbox_config_id parameter (required)
- `user-id`: user-id parameter
### delete_sandbox_config_v1_sandbox_config__sandbox_config_id__delete
- **ID**: `DELETE-v1-sandbox-config-sandbox-config-id`
- **Description**: Make a DELETE request to /v1/sandbox-config/{sandbox_config_id}
- **Method**: `DELETE`
- **Path**: `/v1/sandbox-config/{sandbox_config_id}`
**Parameters**:
- `sandbox_config_id`: sandbox_config_id parameter (required)
- `user-id`: user-id parameter
### force_recreate_local_sandbox_venv_v1_sandbox_config_local_recreate_venv_post
- **ID**: `POST-v1-sandbox-config-local-recreate-venv`
- **Description**: Forcefully recreate the virtual environment for the local sandbox.
Deletes and recreates the venv, then reinstalls required dependencies.
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/local/recreate-venv`
**Parameters**:
- `user-id`: user-id parameter
### create_sandbox_env_var_v1_sandbox_config__sandbox_config_id__environment_variable_post
- **ID**: `POST-v1-sandbox-config-sandbox-config-id-environment-variable`
- **Description**: Make a POST request to /v1/sandbox-config/{sandbox_config_id}/environment-variable
- **Method**: `POST`
- **Path**: `/v1/sandbox-config/{sandbox_config_id}/environment-variable`
**Parameters**:
- `sandbox_config_id`: sandbox_config_id parameter (required)
- `user-id`: user-id parameter
### list_sandbox_env_vars_v1_sandbox_config__sandbox_config_id__environment_variable_get
- **ID**: `GET-v1-sandbox-config-sandbox-config-id-environment-variable`
- **Description**: Make a GET request to /v1/sandbox-config/{sandbox_config_id}/environment-variable
- **Method**: `GET`
- **Path**: `/v1/sandbox-config/{sandbox_config_id}/environment-variable`
**Parameters**:
- `sandbox_config_id`: sandbox_config_id parameter (required)
- `limit`: Number of results to return
- `after`: Pagination cursor to fetch the next set of results
- `user-id`: user-id parameter
### update_sandbox_env_var_v1_sandbox_config_environment_variable__env_var_id__patch
- **ID**: `PATCH-v1-sandbox-config-environment-variable-env-var-id`
- **Description**: Make a PATCH request to /v1/sandbox-config/environment-variable/{env_var_id}
- **Method**: `PATCH`
- **Path**: `/v1/sandbox-config/environment-variable/{env_var_id}`
**Parameters**:
- `env_var_id`: env_var_id parameter (required)
- `user-id`: user-id parameter
### delete_sandbox_env_var_v1_sandbox_config_environment_variable__env_var_id__delete
- **ID**: `DELETE-v1-sandbox-config-environment-variable-env-var-id`
- **Description**: Make a DELETE request to /v1/sandbox-config/environment-variable/{env_var_id}
- **Method**: `DELETE`
- **Path**: `/v1/sandbox-config/environment-variable/{env_var_id}`
**Parameters**:
- `env_var_id`: env_var_id parameter (required)
- `user-id`: user-id parameter
### list_providers
- **ID**: `GET-v1-providers-`
- **Description**: Get a list of all custom providers in the database
- **Method**: `GET`
- **Path**: `/v1/providers/`
**Parameters**:
- `after`: after parameter
- `limit`: limit parameter
- `user_id`: user_id parameter
### create_provider
- **ID**: `POST-v1-providers-`
- **Description**: Create a new custom provider
- **Method**: `POST`
- **Path**: `/v1/providers/`
**Parameters**:
- `user_id`: user_id parameter
### modify_provider
- **ID**: `PATCH-v1-providers-`
- **Description**: Update an existing custom provider
- **Method**: `PATCH`
- **Path**: `/v1/providers/`
**Parameters**:
- `user_id`: user_id parameter
### delete_provider
- **ID**: `DELETE-v1-providers-`
- **Description**: Delete an existing custom provider
- **Method**: `DELETE`
- **Path**: `/v1/providers/`
**Parameters**:
- `provider_id`: The provider_id key to be deleted. (required)
- `user_id`: user_id parameter
### list_runs
- **ID**: `GET-v1-runs-`
- **Description**: List all runs.
- **Method**: `GET`
- **Path**: `/v1/runs/`
**Parameters**:
- `user_id`: user_id parameter
### list_active_runs
- **ID**: `GET-v1-runs-active`
- **Description**: List all active runs.
- **Method**: `GET`
- **Path**: `/v1/runs/active`
**Parameters**:
- `user_id`: user_id parameter
### retrieve_run
- **ID**: `GET-v1-runs-run-id`
- **Description**: Get the status of a run.
- **Method**: `GET`
- **Path**: `/v1/runs/{run_id}`
**Parameters**:
- `run_id`: run_id parameter (required)
- `user_id`: user_id parameter
### delete_run
- **ID**: `DELETE-v1-runs-run-id`
- **Description**: Delete a run by its run_id.
- **Method**: `DELETE`
- **Path**: `/v1/runs/{run_id}`
**Parameters**:
- `run_id`: run_id parameter (required)
- `user_id`: user_id parameter
### list_run_messages
- **ID**: `GET-v1-runs-run-id-messages`
- **Description**: Get messages associated with a run with filtering options.
Args:
run_id: ID of the run
before: A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
after: A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: Maximum number of messages to return
order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
role: Filter by role (user/assistant/system/tool)
return_message_object: Whether to return Message objects or LettaMessage objects
user_id: ID of the user making the request
Returns:
A list of messages associated with the run. Default is List[LettaMessage].
- **Method**: `GET`
- **Path**: `/v1/runs/{run_id}/messages`
**Parameters**:
- `run_id`: run_id parameter (required)
- `before`: Cursor for pagination
- `after`: Cursor for pagination
- `limit`: Maximum number of messages to return
- `order`: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- `role`: Filter by role
- `user_id`: user_id parameter
### retrieve_run_usage
- **ID**: `GET-v1-runs-run-id-usage`
- **Description**: Get usage statistics for a run.
- **Method**: `GET`
- **Path**: `/v1/runs/{run_id}/usage`
**Parameters**:
- `run_id`: run_id parameter (required)
- `user_id`: user_id parameter
### list_run_steps
- **ID**: `GET-v1-runs-run-id-steps`
- **Description**: Get messages associated with a run with filtering options.
Args:
run_id: ID of the run
before: A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
after: A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: Maximum number of steps to return
order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
Returns:
A list of steps associated with the run.
- **Method**: `GET`
- **Path**: `/v1/runs/{run_id}/steps`
**Parameters**:
- `run_id`: run_id parameter (required)
- `before`: Cursor for pagination
- `after`: Cursor for pagination
- `limit`: Maximum number of messages to return
- `order`: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- `user_id`: user_id parameter
### list_steps
- **ID**: `GET-v1-steps`
- **Description**: 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)
- **Method**: `GET`
- **Path**: `/v1/steps`
**Parameters**:
- `before`: Return steps before this step ID
- `after`: Return steps after this step ID
- `limit`: Maximum number of steps to return
- `order`: Sort order (asc or desc)
- `start_date`: Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
- `end_date`: Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
- `model`: Filter by the name of the model used for the step
- `agent_id`: Filter by the ID of the agent that performed the step
- `user_id`: user_id parameter
### retrieve_step
- **ID**: `GET-v1-steps-step-id`
- **Description**: Get a step by ID.
- **Method**: `GET`
- **Path**: `/v1/steps/{step_id}`
**Parameters**:
- `step_id`: step_id parameter (required)
- `user_id`: user_id parameter
### update_step_transaction_id
- **ID**: `PATCH-v1-steps-step-id-transaction-transaction-id`
- **Description**: Update the transaction ID for a step.
- **Method**: `PATCH`
- **Path**: `/v1/steps/{step_id}/transaction/{transaction_id}`
**Parameters**:
- `step_id`: step_id parameter (required)
- `transaction_id`: transaction_id parameter (required)
- `user_id`: user_id parameter
### list_tags
- **ID**: `GET-v1-tags-`
- **Description**: Get a list of all tags in the database
- **Method**: `GET`
- **Path**: `/v1/tags/`
**Parameters**:
- `after`: after parameter
- `limit`: limit parameter
- `query_text`: query_text parameter
- `user_id`: user_id parameter
### create_voice_chat_completions
- **ID**: `POST-v1-voice-beta-agent-id-chat-completions`
- **Description**: Make a POST request to /v1/voice-beta/{agent_id}/chat/completions
- **Method**: `POST`
- **Path**: `/v1/voice-beta/{agent_id}/chat/completions`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user-id`: user-id parameter
### list_users
- **ID**: `GET-v1-admin-users-`
- **Description**: Get a list of all users in the database
- **Method**: `GET`
- **Path**: `/v1/admin/users/`
**Parameters**:
- `after`: after parameter
- `limit`: limit parameter
### create_user
- **ID**: `POST-v1-admin-users-`
- **Description**: Create a new user in the database
- **Method**: `POST`
- **Path**: `/v1/admin/users/`
No parameters required.
### update_user
- **ID**: `PUT-v1-admin-users-`
- **Description**: Update a user in the database
- **Method**: `PUT`
- **Path**: `/v1/admin/users/`
No parameters required.
### delete_user
- **ID**: `DELETE-v1-admin-users-`
- **Description**: Make a DELETE request to /v1/admin/users/
- **Method**: `DELETE`
- **Path**: `/v1/admin/users/`
**Parameters**:
- `user_id`: The user_id key to be deleted. (required)
### list_orgs
- **ID**: `GET-v1-admin-orgs-`
- **Description**: Get a list of all orgs in the database
- **Method**: `GET`
- **Path**: `/v1/admin/orgs/`
**Parameters**:
- `after`: after parameter
- `limit`: limit parameter
### create_organization
- **ID**: `POST-v1-admin-orgs-`
- **Description**: Create a new org in the database
- **Method**: `POST`
- **Path**: `/v1/admin/orgs/`
No parameters required.
### delete_organization_by_id
- **ID**: `DELETE-v1-admin-orgs-`
- **Description**: Make a DELETE request to /v1/admin/orgs/
- **Method**: `DELETE`
- **Path**: `/v1/admin/orgs/`
**Parameters**:
- `org_id`: The org_id key to be deleted. (required)
### update_organization
- **ID**: `PATCH-v1-admin-orgs-`
- **Description**: Make a PATCH request to /v1/admin/orgs/
- **Method**: `PATCH`
- **Path**: `/v1/admin/orgs/`
**Parameters**:
- `org_id`: The org_id key to be updated. (required)
### create_chat_completions
- **ID**: `POST-openai-v1-agent-id-chat-completions`
- **Description**: Make a POST request to /openai/v1/{agent_id}/chat/completions
- **Method**: `POST`
- **Path**: `/openai/v1/{agent_id}/chat/completions`
**Parameters**:
- `agent_id`: agent_id parameter (required)
- `user-id`: user-id parameter
### authenticate_user_v1_auth_post
- **ID**: `POST-v1-auth`
- **Description**: Authenticates the user and sends response with User related data.
Currently, this is a placeholder that simply returns a UUID placeholder
- **Method**: `POST`
- **Path**: `/v1/auth`
No parameters required.
## License
MIT