Letta Internal Templates API

openapi: 3.1.0
info:
  title: Letta Admin Internal Templates API
  version: 1.0.0
  description: REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283.
  contact:
    name: Letta
    url: https://www.letta.com/
    email: support@letta.com
  license:
    name: Apache-2.0
    url: https://github.com/letta-ai/letta/blob/main/LICENSE
  x-logo:
    url: https://www.letta.com/favicon.ico
servers:
- url: https://api.letta.com
  description: Letta Cloud (managed)
- url: https://app.letta.com
  description: Letta Cloud (app)
- url: http://localhost:8283
  description: Self-hosted Letta server
security:
- bearerAuth: []
tags:
- name: Internal Templates
  description: Internal Templates operations.
paths:
  /v1/_internal_templates/groups:
    post:
      tags:
      - Internal Templates
      summary: Create Group
      description: Create a new multi-agent group with the specified configuration.
      operationId: create_internal_template_group
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalTemplateGroupCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/_internal_templates/agents:
    post:
      tags:
      - Internal Templates
      summary: Create Agent
      description: Create a new agent with template-related fields.
      operationId: create_internal_template_agent
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalTemplateAgentCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentState'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/_internal_templates/blocks:
    post:
      tags:
      - Internal Templates
      summary: Create Block
      description: Create a new block with template-related fields.
      operationId: create_internal_template_block
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalTemplateBlockCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/_internal_templates/blocks/batch:
    post:
      tags:
      - Internal Templates
      summary: Create Blocks Batch
      description: Create multiple blocks with template-related fields.
      operationId: create_internal_template_blocks_batch
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/InternalTemplateBlockCreate'
              title: Blocks
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
                title: Response Create Internal Template Blocks Batch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/_internal_templates/deployment/{deployment_id}:
    get:
      tags:
      - Internal Templates
      summary: List Deployment Entities
      description: 'List all entities (blocks, agents, groups) with the specified deployment_id.

        Optionally filter by entity types.'
      operationId: list_deployment_entities
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          title: Deployment Id
      - name: entity_types
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by entity types (block, agent, group)
          title: Entity Types
        description: Filter by entity types (block, agent, group)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeploymentEntitiesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Internal Templates
      summary: Delete Deployment
      description: 'Delete all entities (blocks, agents, groups) with the specified deployment_id.

        Deletion order: blocks -> agents -> groups to maintain referential integrity.'
      operationId: delete_deployment
      parameters:
      - name: deployment_id
        in: path
        required: true
        schema:
          type: string
          title: Deployment Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDeploymentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentEnvironmentVariable:
      properties:
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
          description: The id of the user that made this object.
        last_updated_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated By Id
          description: The id of the user that made this object.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: The timestamp when the object was created.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: The timestamp when the object was last updated.
        id:
          type: string
          pattern: ^agent-env-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the Agent-env
          examples:
          - agent-env-123e4567-e89b-12d3-a456-426614174000
        key:
          type: string
          title: Key
          description: The name of the environment variable.
        value:
          type: string
          title: Value
          description: The value of the environment variable.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: An optional description of the environment variable.
        value_enc:
          anyOf:
          - type: string
            description: Encrypted secret value (stored as encrypted string)
            nullable: true
          - type: 'null'
          title: Value Enc
          description: Encrypted value as Secret object
        agent_id:
          type: string
          title: Agent Id
          description: The ID of the agent this environment variable belongs to.
      additionalProperties: false
      type: object
      required:
      - key
      - value
      - agent_id
      title: AgentEnvironmentVariable
    ToolType:
      type: string
      enum:
      - custom
      - letta_core
      - letta_memory_core
      - letta_multi_agent_core
      - letta_sleeptime_core
      - letta_voice_sleeptime_core
      - letta_builtin
      - letta_files_core
      - external_langchain
      - external_composio
      - external_mcp
      title: ToolType
    InternalTemplateBlockCreate:
      properties:
        value:
          type: string
          title: Value
          description: Value of the block.
        limit:
          type: integer
          title: Limit
          description: Character limit of the block.
          default: 100000
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: The associated project id.
        template_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Name
          description: Name of the block if it is a template.
        is_template:
          type: boolean
          title: Is Template
          default: false
        template_id:
          type: string
          title: Template Id
          description: The id of the template.
        base_template_id:
          type: string
          title: Base Template Id
          description: The id of the base template.
        deployment_id:
          type: string
          title: Deployment Id
          description: The id of the deployment.
        entity_id:
          type: string
          title: Entity Id
          description: The id of the entity within the template.
        preserve_on_migration:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Preserve On Migration
          description: Preserve the block on template migration.
          default: false
        label:
          type: string
          title: Label
          description: Label of the block.
        read_only:
          type: boolean
          title: Read Only
          description: Whether the agent has read-only access to the block.
          default: false
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the block.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata of the block.
          default: {}
        hidden:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hidden
          description: If set to True, the block will be hidden.
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: The tags to associate with the block.
      type: object
      required:
      - value
      - template_id
      - base_template_id
      - deployment_id
      - entity_id
      - label
      title: InternalTemplateBlockCreate
      description: Used for Letta Cloud
    ConditionalToolRule:
      properties:
        tool_name:
          type: string
          title: Tool Name
          description: The name of the tool. Must exist in the database for the user's organization.
        type:
          type: string
          const: conditional
          title: Type
          default: conditional
        prompt_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Template
          description: Optional template string (ignored).
        default_child:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Child
          description: The default child tool to be called. If None, any tool can be called.
        child_output_mapping:
          additionalProperties:
            type: string
          type: object
          title: Child Output Mapping
          description: The output case to check for mapping
        require_output_mapping:
          type: boolean
          title: Require Output Mapping
          description: Whether to throw an error when output doesn't match any case
          default: false
      additionalProperties: false
      type: object
      required:
      - tool_name
      - child_output_mapping
      title: ConditionalToolRule
      description: A ToolRule that conditionally maps to different child tools based on the output.
    ZAIThinking:
      properties:
        type:
          type: string
          enum:
          - enabled
          - disabled
          title: Type
          description: Whether thinking is enabled or disabled.
          default: enabled
        clear_thinking:
          type: boolean
          title: Clear Thinking
          description: If False, preserved thinking is used (recommended for agents).
          default: false
      type: object
      title: ZAIThinking
      description: Thinking configuration for ZAI GLM-4.5+ models.
    ToolCallContent:
      properties:
        type:
          type: string
          const: tool_call
          title: Type
          description: Indicates this content represents a tool call event.
          default: tool_call
        id:
          type: string
          title: Id
          description: A unique identifier for this specific tool call instance.
        name:
          type: string
          title: Name
          description: The name of the tool being called.
        input:
          additionalProperties: true
          type: object
          title: Input
          description: The parameters being passed to the tool, structured as a dictionary of parameter names to values.
        signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature
          description: Stores a unique identifier for any reasoning associated with this tool call.
      type: object
      required:
      - id
      - name
      - input
      title: ToolCallContent
    TextContent:
      properties:
        type:
          type: string
          const: text
          title: Type
          description: The type of the message.
          default: text
        text:
          type: string
          title: Text
          description: The text content of the message.
        signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature
          description: Stores a unique identifier for any reasoning associated with this text content.
      type: object
      required:
      - text
      title: TextContent
    RequiresApprovalToolRule:
      properties:
        tool_name:
          type: string
          title: Tool Name
          description: The name of the tool. Must exist in the database for the user's organization.
        type:
          type: string
          const: requires_approval
          title: Type
          default: requires_approval
        prompt_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Template
          description: Optional template string (ignored). Rendering uses fast built-in formatting for performance.
      additionalProperties: false
      type: object
      required:
      - tool_name
      title: RequiresApprovalToolRule
      description: Represents a tool rule configuration which requires approval before the tool can be invoked.
    ManagerType:
      type: string
      enum:
      - round_robin
      - supervisor
      - dynamic
      - sleeptime
      - voice_sleeptime
      - swarm
      title: ManagerType
    CompactionSettings-Output:
      properties:
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: 'Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.'
        model_settings:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/OpenAIModelSettings'
            - $ref: '#/components/schemas/SGLangModelSettings'
            - $ref: '#/components/schemas/AnthropicModelSettings'
            - $ref: '#/components/schemas/GoogleAIModelSettings'
            - $ref: '#/components/schemas/GoogleVertexModelSettings'
            - $ref: '#/components/schemas/AzureModelSettings'
            - $ref: '#/components/schemas/XAIModelSettings'
            - $ref: '#/components/schemas/ZAIModelSettings'
            - $ref: '#/components/schemas/GroqModelSettings'
            - $ref: '#/components/schemas/DeepseekModelSettings'
            - $ref: '#/components/schemas/TogetherModelSettings'
            - $ref: '#/components/schemas/BedrockModelSettings'
            - $ref: '#/components/schemas/BasetenModelSettings'
            - $ref: '#/components/schemas/OpenRouterModelSettings'
            - $ref: '#/components/schemas/ChatGPTOAuthModelSettings'
            discriminator:
              propertyName: provider_type
              mapping:
                anthropic: '#/components/schemas/AnthropicModelSettings'
                azure: '#/components/schemas/AzureModelSettings'
                baseten: '#/components/schemas/BasetenModelSettings'
                bedrock: '#/components/schemas/BedrockModelSettings'
                chatgpt_oauth: '#/components/schemas/ChatGPTOAuthModelSettings'
                deepseek: '#/components/schemas/DeepseekModelSettings'
                google_ai: '#/components/schemas/GoogleAIModelSettings'
                google_vertex: '#/components/schemas/GoogleVertexModelSettings'
                groq: '#/components/schemas/GroqModelSettings'
                openai: '#/components/schemas/OpenAIModelSettings'
                openrouter: '#/components/schemas/OpenRouterModelSettings'
                sglang: '#/components/schemas/SGLangModelSettings'
                together: '#/components/schemas/TogetherModelSettings'
                xai: '#/components/schemas/XAIModelSettings'
                zai: '#/components/schemas/ZAIModelSettings'
          - type: 'null'
          title: Model Settings
          description: Optional model settings used to override defaults for the summarizer model.
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: The prompt to use for summarization. If None, uses mode-specific default.
        prompt_acknowledgement:
          type: boolean
          title: Prompt Acknowledgement
          description: Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs).
          default: false
        clip_chars:
          anyOf:
          - type: integer
          - type: 'null'
          title: Clip Chars
          description: The maximum length of the summary in characters. If none, no clipping is performed.
          default: 50000
        mode:
          type: string
          enum:
          - all
          - sliding_window
          - self_compact_all
          - self_compact_sliding_window
          title: Mode
          description: The type of summarization technique use.
          default: sliding_window
        sliding_window_percentage:
          type: number
          title: Sliding Window Percentage
          description: The percentage of the context window to keep post-summarization (only used in sliding window modes).
      type: object
      title: CompactionSettings
      description: 'Configuration for conversation compaction / summarization.


        Per-model settings (temperature,

        max tokens, etc.) are derived from the default configuration for that handle.'
    DeleteDeploymentResponse:
      properties:
        deleted_blocks:
          items:
            type: string
          type: array
          title: Deleted Blocks
          default: []
        deleted_agents:
          items:
            type: string
          type: array
          title: Deleted Agents
          default: []
        deleted_groups:
          items:
            type: string
          type: array
          title: Deleted Groups
          default: []
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: DeleteDeploymentResponse
      description: Response model for delete deployment operation.
    Group:
      properties:
        id:
          type: string
          title: Id
          description: The id of the group. Assigned by the database.
        manager_type:
          $ref: '#/components/schemas/ManagerType'
          description: ''
        agent_ids:
          items:
            type: string
          type: array
          title: Agent Ids
          description: ''
        description:
          type: string
          title: Description
          description: ''
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: The associated project id.
        template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Id
          description: The id of the template.
        base_template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Template Id
          description: The base template id.
        deployment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Deployment Id
          description: The id of the deployment.
        shared_block_ids:
          items:
            type: string
          type: array
          title: Shared Block Ids
          description: ''
          default: []
          deprecated: true
        manager_agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Manager Agent Id
          description: ''
        termination_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Termination Token
          description: ''
        max_turns:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Turns
          description: ''
        sleeptime_agent_frequency:
          anyOf:
          - type: integer
          - type: 'null'
          title: Sleeptime Agent Frequency
          description: ''
        turns_counter:
          anyOf:
          - type: integer
          - type: 'null'
          title: Turns Counter
          description: ''
        last_processed_message_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Processed Message Id
          description: ''
        max_message_buffer_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Message Buffer Length
          description: The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving.
        min_message_buffer_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Message Buffer Length
          description: The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving.
        hidden:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hidden
          description: If set to True, the group will be hidden.
      additionalProperties: false
      type: object
      required:
      - id
      - manager_type
      - agent_ids
      - description
      title: Group
    FileBlock:
      properties:
        value:
          type: string
          title: Value
          description: Value of the block.
        limit:
          type: integer
          title: Limit
          description: Character limit of the block.
          default: 100000
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: The associated project id.
        template_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Name
          description: Name of the block if it is a template.
        is_template:
          type: boolean
          title: Is Template
          description: Whether the block is a template (e.g. saved human/persona options).
          default: false
        template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Id
          description: The id of the template.
        base_template_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Template Id
          description: The base template id of the block.
        deployment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Deployment Id
          description: The id of the deployment.
        entity_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Id
          description: The id of the entity within the template.
        preserve_on_migration:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Preserve On Migration
          description: Preserve the block on template migration.
          default: false
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Label of the block (e.g. 'human', 'persona') in the context window.
        read_only:
          type: boolean
          title: Read Only
          description: Whether the agent has read-only access to the block.
          default: false
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the block.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata of the block.
          default: {}
        hidden:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hidden
          description: If set to True, the block will be hidden.
        id:
          type: string
          pattern: ^block-[a-fA-F0-9]{8}
          title: Id
          description: The human-friendly ID of the Block
          examples:
          - block-123e4567-e89b-12d3-a456-426614174000
        created_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Id
          description: The id of the user that made this Block.
        last_updated_by_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated By Id
          description: The id of the user that last updated this Block.
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: The tags associated with the block.
          default: []
        file_id:
          type: string
          title: File Id
          description: Unique identifier of the file.
        source_id:
          type: string
          title: Source Id
          description: 'Deprecated: Use `folder_id` field instead. Unique identifier of the source.'
          deprecated: true
        is_open:
          type: boolean
          title: Is Open
          description: True if the agent currently has the file open.
        last_accessed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Accessed At
          description: UTC timestamp of the agent’s most recent access to this file. Any operations from the open, close, or search tools will update this field.
      type: object
      required:
      - value
      - file_id
      - source_id
      - is_open
      title: FileBlock
    GeminiThinkingConfig:
      properties:
        include_thoughts:
          type: boolean
          title: Include Thoughts
          description: Whether to include thoughts in the model's response.
          default: true
        thinking_budget:
          type: integer
          title: Thinking Budget
          description: The thinking budget for the model.
          default: 1024
      type: object
      title: GeminiThinkingConfig
    OpenAIReasoning:
      properties:
        reasoning_effort:
          type: string
          enum:
          - none
          - minimal
          - low
          - medium
          - high
          - xhigh
          title: Reasoning Effort
          description: The reasoning effort to use when generating text reasoning models
          default: minimal
      type: object
      title: OpenAIReasoning
    LettaImage:
      properties:
        type:
          type: string
          const: letta
          title: Type
          description: The source type for the image.
          default: letta
        file_id:
          type: string
          title: File Id
          description: The unique identifier of the image file persisted in storage.
        media_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Type
          description: The media type for the image.
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
          description: The base64 encoded image data.
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
          description: What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
      type: object
      required:
      - file_id
      title: LettaImage
    XAIModelSettings:
      properties:
        max_output_tokens:
          type: integer
          title: Max Output Tokens
          description: The maximum number of tokens the model can generate.
          default: 4096
        parallel_tool_calls:
          type: boolean
          title: Parallel Tool Calls
          description: Whether to enable parallel tool calling.
          default: true
        provider_type:
          type: string
          const: xai
          title: Provider Type
          description: The type of the provider.
          default: xai
        temperature:
          type: number
          title: Temperature
          description: The temperature of the model.
          default: 0.7
        response_format:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/TextResponseFormat'
            - $ref: '#/components/schemas/JsonSchemaResponseFormat'
            - $ref: '#/components/schemas/JsonObjectResponseFormat'
            discriminator:
              propertyName: type
              mapping:
                json_object: '#/components/schemas/JsonObjectResponseFormat'
                json_schema: '#/components/schemas/JsonSchemaResponseFormat'
                text: '#/components/schemas/TextResponseFormat'
          - type: 'null'
          title: Response Format
          description: The response format for the model.
      type: object
      title: XAIModelSettings
      description: xAI model configuration (OpenAI-compatible).
    VoiceSleeptimeManager:
      properties:
        manager_type:
          type: string
          const: voice_sleeptime
          title: Manager Type
          description: ''
          default: voice_sleeptime
        manager_agent_id:
          type: string
          maxLength: 42
          minLength: 42
          pattern: ^agent-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          title: Manager Agent Id
          description: ''
          examples:
          - agent-123e4567-e

# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-internal-templates-api-openapi.yml