openapi: 3.1.0
info:
title: Letta Admin 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: Templates
description: Reusable agent templates for instantiation.
paths:
/v1/templates/{project_id}/{template_version}/agents:
post:
description: Creates an Agent or multiple Agents from a template
summary: Create Agents from Template
tags:
- Templates
parameters:
- name: project_id
in: path
required: true
schema:
type: string
description: The project id
- name: template_version
in: path
required: true
schema:
type: string
description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta.
operationId: templates.createAgentsFromTemplate
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties:
tags:
type: array
items:
type: string
pattern: ^[a-zA-Z0-9-_ ]*$
description: The tags to assign to the agent
agent_name:
type: string
pattern: ^[a-zA-Z0-9-_ ]*$
description: The name of the agent, optional otherwise a random one will be assigned
initial_message_sequence:
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
- system
- assistant
content:
type: string
name:
type: string
nullable: true
otid:
type: string
nullable: true
sender_id:
type: string
nullable: true
batch_item_id:
type: string
nullable: true
group_id:
type: string
nullable: true
required:
- role
- content
description: Set an initial sequence of messages, if not provided, the agent will start with the default message sequence, if an empty array is provided, the agent will start with no messages
memory_variables:
type: object
additionalProperties:
type: string
description: The memory variables to assign to the agent
tool_variables:
type: object
additionalProperties:
type: string
description: The tool variables to assign to the agent
identity_ids:
type: array
items:
type: string
description: The identity ids to assign to the agent
responses:
'201':
description: '201'
'402':
description: '402'
content:
application/json:
schema:
type: object
properties:
message:
type: string
limit:
type: number
required:
- message
- limit
/v1/templates/{template_version}/agents:
post:
description: Creates an Agent or multiple Agents from a template
summary: Create Agents from Template
tags:
- Templates
parameters:
- name: template_version
in: path
required: true
schema:
type: string
description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest. This endpoint is not available for self-hosted Letta.
operationId: templates.createAgentsFromTemplateNoProject
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties:
tags:
type: array
items:
type: string
pattern: ^[a-zA-Z0-9-_ ]*$
description: The tags to assign to the agent
agent_name:
type: string
pattern: ^[a-zA-Z0-9-_ ]*$
description: The name of the agent, optional otherwise a random one will be assigned
initial_message_sequence:
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
- system
- assistant
content:
type: string
name:
type: string
nullable: true
otid:
type: string
nullable: true
sender_id:
type: string
nullable: true
batch_item_id:
type: string
nullable: true
group_id:
type: string
nullable: true
required:
- role
- content
description: Set an initial sequence of messages, if not provided, the agent will start with the default message sequence, if an empty array is provided, the agent will start with no messages
memory_variables:
type: object
additionalProperties:
type: string
description: The memory variables to assign to the agent
tool_variables:
type: object
additionalProperties:
type: string
description: The tool variables to assign to the agent
identity_ids:
type: array
items:
type: string
description: The identity ids to assign to the agent
responses:
'201':
description: '201'
content:
application/json:
schema:
type: object
properties:
agent_ids:
type: array
items:
type: string
description: Array of created agent IDs
group_id:
type: string
nullable: true
description: Optional group ID if agents were created in a group
deployment_id:
type: string
description: The deployment ID for the created agents
required:
- agent_ids
- group_id
- deployment_id
description: Response containing created agent IDs and associated metadata
'402':
description: '402'
content:
application/json:
schema:
type: object
properties:
message:
type: string
limit:
type: number
required:
- message
- limit
/v1/templates:
get:
description: List all templates
summary: List Templates (Cloud-only)
tags:
- Templates
parameters:
- name: offset
in: query
schema:
oneOf:
- type: string
- type: number
- name: exact
in: query
description: Whether to search for an exact name match
schema:
type: string
- name: limit
in: query
schema:
type: string
- name: version
in: query
description: Specify the version you want to return, otherwise will return the latest version
schema:
type: string
- name: template_id
in: query
schema:
type: string
- name: name
in: query
schema:
type: string
- name: search
in: query
schema:
type: string
- name: project_slug
in: query
schema:
type: string
- name: project_id
in: query
schema:
type: string
- name: sort_by
in: query
schema:
type: string
enum:
- updated_at
- created_at
operationId: templates.listTemplates
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
templates:
type: array
items:
type: object
properties:
name:
type: string
description: The exact name of the template
id:
type: string
project_id:
type: string
project_slug:
type: string
latest_version:
type: string
description: The latest version of the template
description:
type: string
template_deployment_slug:
type: string
description: The full name of the template, including version and project slug
updated_at:
type: string
description: When the template was last updated
required:
- name
- id
- project_id
- project_slug
- latest_version
- template_deployment_slug
- updated_at
has_next_page:
type: boolean
required:
- templates
- has_next_page
post:
description: Creates a new template from an existing agent or agent file
summary: Create Template (Cloud-only)
tags:
- Templates
parameters: []
operationId: templates.createTemplateNoProject
requestBody:
description: Body
content:
application/json:
schema:
discriminator:
propertyName: type
oneOf:
- type: object
properties:
type:
type: string
enum:
- agent
agent_id:
type: string
description: The ID of the agent to use as a template, can be from any project
name:
type: string
pattern: ^[a-zA-Z0-9_-]+$
description: Optional custom name for the template. If not provided, a random name will be generated.
required:
- type
- agent_id
summary: From Agent
description: Create a template from an existing agent
- type: object
properties:
type:
type: string
enum:
- agent_file
agent_file:
type: object
additionalProperties:
nullable: true
description: The agent file to use as a template, this should be a JSON file exported from the platform
name:
type: string
pattern: ^[a-zA-Z0-9_-]+$
description: Optional custom name for the template. If not provided, a random name will be generated.
update_existing_tools:
type: boolean
description: If true, update existing custom tools source_code and json_schema (source_type cannot be changed)
required:
- type
- agent_file
summary: From Agent File
description: Create a template from an uploaded agent file
summary: Create template
description: The type of template to create, currently only agent templates are supported
responses:
'201':
description: '201'
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The exact name of the template
id:
type: string
project_id:
type: string
project_slug:
type: string
latest_version:
type: string
description: The latest version of the template
description:
type: string
template_deployment_slug:
type: string
description: The full name of the template, including version and project slug
updated_at:
type: string
description: When the template was last updated
required:
- name
- id
- project_id
- project_slug
- latest_version
- template_deployment_slug
- updated_at
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
/v1/templates/{template_name}/save:
post:
description: Saves the current version of the template as a new version
summary: Save Template Version (Cloud-only)
tags:
- Templates
parameters:
- name: template_name
in: path
required: true
schema:
type: string
description: The template version, formatted as {template-name}, any version appended will be ignored
operationId: templates.saveTemplateVersionNoProject
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties:
preserve_environment_variables_on_migration:
type: boolean
description: If true, the environment variables will be preserved in the template version when migrating agents
preserve_core_memories_on_migration:
type: boolean
description: If true, the core memories will be preserved in the template version when migrating agents
preserve_sources_on_migration:
type: boolean
description: If true, existing agent folders/sources will be preserved and merged with template sources during migration. If false, agent sources will be replaced with template sources.
block_reconciliation_strategy:
type: string
enum:
- reconcile-all
- preserve-deleted
description: 'Strategy for reconciling memory blocks during migration: "reconcile-all" deletes blocks not in the template, "preserve-deleted" keeps them. Defaults to "preserve-deleted".'
migrate_agents:
type: boolean
description: If true, existing agents attached to this template will be migrated to the new template version
message:
type: string
description: A message to describe the changes made in this template version
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The exact name of the template
id:
type: string
project_id:
type: string
project_slug:
type: string
latest_version:
type: string
description: The latest version of the template
description:
type: string
template_deployment_slug:
type: string
description: The full name of the template, including version and project slug
updated_at:
type: string
description: When the template was last updated
required:
- name
- id
- project_id
- project_slug
- latest_version
- template_deployment_slug
- updated_at
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
/v1/templates/{project_id}/{template_name}:
post:
description: Saves the current version of the template as a new version
summary: Save Template Version (Cloud-only)
tags:
- Templates
parameters:
- name: project_id
in: path
required: true
schema:
type: string
description: The project id
- name: template_name
in: path
required: true
schema:
type: string
description: The template version, formatted as {template-name}, any version appended will be ignored
operationId: templates.saveTemplateVersion
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties:
preserve_environment_variables_on_migration:
type: boolean
description: If true, the environment variables will be preserved in the template version when migrating agents
preserve_core_memories_on_migration:
type: boolean
description: If true, the core memories will be preserved in the template version when migrating agents
preserve_sources_on_migration:
type: boolean
description: If true, existing agent folders/sources will be preserved and merged with template sources during migration. If false, agent sources will be replaced with template sources.
block_reconciliation_strategy:
type: string
enum:
- reconcile-all
- preserve-deleted
description: 'Strategy for reconciling memory blocks during migration: "reconcile-all" deletes blocks not in the template, "preserve-deleted" keeps them. Defaults to "preserve-deleted".'
migrate_agents:
type: boolean
description: If true, existing agents attached to this template will be migrated to the new template version
message:
type: string
description: A message to describe the changes made in this template version
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The exact name of the template
id:
type: string
project_id:
type: string
project_slug:
type: string
latest_version:
type: string
description: The latest version of the template
description:
type: string
template_deployment_slug:
type: string
description: The full name of the template, including version and project slug
updated_at:
type: string
description: When the template was last updated
required:
- name
- id
- project_id
- project_slug
- latest_version
- template_deployment_slug
- updated_at
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
delete:
description: Deletes all versions of a template with the specified name
summary: Delete Template (Cloud-only)
tags:
- Templates
parameters:
- name: project_id
in: path
required: true
schema:
type: string
description: The project id
- name: template_name
in: path
required: true
schema:
type: string
description: The template name (without version)
operationId: templates.deleteTemplate
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties: {}
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
'404':
description: '404'
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
/v1/templates/{project_id}/{template_version}/snapshot:
get:
description: Get a snapshot of the template version, this will return the template state at a specific version
summary: Get Template Snapshot (Cloud-only)
tags:
- Templates
parameters:
- name: project_id
in: path
required: true
schema:
type: string
description: The project id
- name: template_version
in: path
required: true
schema:
type: string
description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest
operationId: templates.getTemplateSnapshot
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
agents:
type: array
items:
type: object
properties:
model:
type: string
systemPrompt:
type: string
toolIds:
type: array
items:
type: string
nullable: true
sourceIds:
type: array
items:
type: string
nullable: true
memoryVariables:
type: object
properties:
version:
type: string
data:
type: array
items:
type: object
properties:
key:
type: string
defaultValue:
type: string
nullable: true
type:
type: string
required:
- key
- type
required:
- version
- data
nullable: true
toolVariables:
type: object
properties:
version:
type: string
data:
type: array
items:
type: object
properties:
key:
type: string
defaultValue:
type: string
nullable: true
type:
type: string
required:
- key
- type
required:
- version
- data
nullable: true
tags:
type: array
items:
type: string
nullable: true
identityIds:
type: array
items:
type: string
nullable: true
toolRules:
type: array
items:
oneOf:
- type: object
properties:
tool_name:
type: string
type:
type: string
enum:
- constrain_child_tools
prompt_template:
type: string
nullable: true
children:
type: array
items:
type: string
child_arg_nodes:
type: array
items:
type: object
properties:
name:
type: string
args:
type: object
additionalProperties: {}
nullable: true
required:
- name
nullable: true
required:
- tool_name
- children
- type: object
properties:
tool_name:
type: string
type:
type: string
enum:
- run_first
prompt_template:
type: string
nullable: true
args:
type: object
additionalProperties: {}
nullable: true
required:
- tool_name
- type: object
properties:
tool_name:
type: string
type:
type: string
enum:
- exit_loop
prompt_template:
type: string
nullable: true
required:
- tool_name
- type: object
properties:
tool_name:
type: string
type:
type: string
enum:
- conditional
prompt_template:
type: string
nullable: true
default_child:
type: string
nullable: true
child_output_mapping:
type: object
additionalProperties:
type: string
require_output_mapping:
type: boolean
required:
- tool_name
- child_output_mapping
- type: object
properties:
tool_name:
type: string
type:
type: string
enum:
- continue_loop
prompt_template:
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-templates-api-openapi.yml