Letta Models API

openapi: 3.1.0
info:
  title: Letta Admin Models 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: Models
  description: List available chat and embedding models exposed by configured providers.
paths:
  /v1/models/:
    get:
      tags:
      - Models
      summary: List LLM Models
      description: 'List available LLM models using the asynchronous implementation for improved performance.


        Returns Model format which extends LLMConfig with additional metadata fields.

        Legacy LLMConfig fields are marked as deprecated but still available for backward compatibility.'
      operationId: list_models
      parameters:
      - name: provider_category
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/ProviderCategory'
          - type: 'null'
          title: Provider Category
      - name: provider_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Name
      - name: provider_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ProviderType'
          - type: 'null'
          title: Provider Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
                title: Response List Models
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/models/embedding:
    get:
      tags:
      - Models
      summary: List Embedding Models
      description: 'List available embedding models using the asynchronous implementation for improved performance.


        Returns EmbeddingModel format which extends EmbeddingConfig with additional metadata fields.

        Legacy EmbeddingConfig fields are marked as deprecated but still available for backward compatibility.'
      operationId: list_embedding_models
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmbeddingModel'
                title: Response List Embedding Models
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/models/embeddings:
    get:
      tags:
      - Models
      parameters: []
      operationId: models.listEmbeddingModels
      responses:
        '200':
          description: '200'
components:
  schemas:
    Model:
      properties:
        handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Handle
          description: The handle for this config, in the format provider/model-name.
        name:
          type: string
          title: Name
          description: The actual model name used by the provider
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: A human-friendly display name for the model.
        provider_type:
          $ref: '#/components/schemas/ProviderType'
          description: The type of the provider
        provider_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Name
          description: The provider name for the model.
        model_type:
          type: string
          const: llm
          title: Model Type
          description: Type of model (llm or embedding)
          default: llm
        model:
          type: string
          title: Model
          description: 'Deprecated: Use ''name'' field instead. LLM model name.'
          deprecated: true
        model_endpoint_type:
          type: string
          enum:
          - openai
          - anthropic
          - google_ai
          - google_vertex
          - azure
          - groq
          - ollama
          - webui
          - webui-legacy
          - lmstudio
          - lmstudio-legacy
          - lmstudio-chatcompletions
          - llamacpp
          - koboldcpp
          - vllm
          - hugging-face
          - baseten
          - minimax
          - mistral
          - together
          - bedrock
          - deepseek
          - xai
          - zai
          - zai_coding
          - openrouter
          - chatgpt_oauth
          title: Model Endpoint Type
          description: 'Deprecated: Use ''provider_type'' field instead. The endpoint type for the model.'
          deprecated: true
        model_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Endpoint
          description: 'Deprecated: The endpoint for the model.'
          deprecated: true
        provider_category:
          anyOf:
          - $ref: '#/components/schemas/ProviderCategory'
          - type: 'null'
          description: 'Deprecated: The provider category for the model.'
          deprecated: true
        model_wrapper:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Wrapper
          description: 'Deprecated: The wrapper for the model.'
          deprecated: true
        context_window:
          type: integer
          title: Context Window
          description: 'Deprecated: Use ''max_context_window'' field instead. The context window size for the model.'
          deprecated: true
        put_inner_thoughts_in_kwargs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Put Inner Thoughts In Kwargs
          description: 'Deprecated: Puts ''inner_thoughts'' as a kwarg in the function call.'
          default: true
          deprecated: true
        temperature:
          type: number
          title: Temperature
          description: 'Deprecated: The temperature to use when generating text with the model.'
          default: 0.7
          deprecated: true
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          description: 'Deprecated: The maximum number of tokens to generate.'
          deprecated: true
        enable_reasoner:
          type: boolean
          title: Enable Reasoner
          description: 'Deprecated: Whether or not the model should use extended thinking if it is a ''reasoning'' style model.'
          default: true
          deprecated: true
        reasoning_effort:
          anyOf:
          - type: string
            enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
          - type: 'null'
          title: Reasoning Effort
          description: 'Deprecated: The reasoning effort to use when generating text reasoning models.'
          deprecated: true
        max_reasoning_tokens:
          type: integer
          title: Max Reasoning Tokens
          description: 'Deprecated: Configurable thinking budget for extended thinking.'
          default: 0
          deprecated: true
        effort:
          anyOf:
          - type: string
            enum:
            - low
            - medium
            - high
            - max
          - type: 'null'
          title: Effort
          description: The effort level for Anthropic models that support it (Opus 4.5, Opus 4.6). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'.
        frequency_penalty:
          anyOf:
          - type: number
          - type: 'null'
          title: Frequency Penalty
          description: 'Deprecated: Positive values penalize new tokens based on their existing frequency in the text so far.'
          deprecated: true
        compatibility_type:
          anyOf:
          - type: string
            enum:
            - gguf
            - mlx
          - type: 'null'
          title: Compatibility Type
          description: 'Deprecated: The framework compatibility type for the model.'
          deprecated: true
        verbosity:
          anyOf:
          - type: string
            enum:
            - low
            - medium
            - high
          - type: 'null'
          title: Verbosity
          description: 'Deprecated: Soft control for how verbose model output should be.'
          deprecated: true
        tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier
          description: 'Deprecated: The cost tier for the model (cloud only).'
          deprecated: true
        parallel_tool_calls:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Parallel Tool Calls
          description: 'Deprecated: If set to True, enables parallel tool calling.'
          default: false
          deprecated: true
        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's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings.
        strict:
          type: boolean
          title: Strict
          description: 'Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.'
          default: false
        return_logprobs:
          type: boolean
          title: Return Logprobs
          description: Whether to return log probabilities of the output tokens. Useful for RL training.
          default: false
        top_logprobs:
          anyOf:
          - type: integer
          - type: 'null'
          title: Top Logprobs
          description: Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True.
        return_token_ids:
          type: boolean
          title: Return Token Ids
          description: Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.
          default: false
        tool_call_parser:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Call Parser
          description: SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output.
        max_context_window:
          type: integer
          title: Max Context Window
          description: The maximum context window for the model
      type: object
      required:
      - name
      - provider_type
      - model
      - model_endpoint_type
      - context_window
      - max_context_window
      title: Model
    JsonObjectResponseFormat:
      properties:
        type:
          type: string
          const: json_object
          title: Type
          description: The type of the response format.
          default: json_object
      type: object
      title: JsonObjectResponseFormat
      description: Response format for JSON object responses.
    EmbeddingModel:
      properties:
        handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Handle
          description: The handle for this config, in the format provider/model-name.
        name:
          type: string
          title: Name
          description: The actual model name used by the provider
        display_name:
          type: string
          title: Display Name
          description: Display name for the model shown in UI
        provider_type:
          $ref: '#/components/schemas/ProviderType'
          description: The type of the provider
        provider_name:
          type: string
          title: Provider Name
          description: The name of the provider
        model_type:
          type: string
          const: embedding
          title: Model Type
          description: Type of model (llm or embedding)
          default: embedding
        embedding_endpoint_type:
          type: string
          enum:
          - openai
          - anthropic
          - bedrock
          - google_ai
          - google_vertex
          - azure
          - groq
          - ollama
          - webui
          - webui-legacy
          - lmstudio
          - lmstudio-legacy
          - llamacpp
          - koboldcpp
          - vllm
          - hugging-face
          - mistral
          - together
          - pinecone
          title: Embedding Endpoint Type
          description: 'Deprecated: Use ''provider_type'' field instead. The endpoint type for the embedding model.'
          deprecated: true
        embedding_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Embedding Endpoint
          description: 'Deprecated: The endpoint for the model.'
          deprecated: true
        embedding_model:
          type: string
          title: Embedding Model
          description: 'Deprecated: Use ''name'' field instead. Embedding model name.'
          deprecated: true
        embedding_dim:
          type: integer
          title: Embedding Dim
          description: The dimension of the embedding
        embedding_chunk_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Embedding Chunk Size
          description: 'Deprecated: The chunk size of the embedding.'
          default: 300
          deprecated: true
        batch_size:
          type: integer
          title: Batch Size
          description: 'Deprecated: The maximum batch size for processing embeddings.'
          default: 32
          deprecated: true
        azure_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Endpoint
          description: 'Deprecated: The Azure endpoint for the model.'
          deprecated: true
        azure_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Version
          description: 'Deprecated: The Azure version for the model.'
          deprecated: true
        azure_deployment:
          anyOf:
          - type: string
          - type: 'null'
          title: Azure Deployment
          description: 'Deprecated: The Azure deployment for the model.'
          deprecated: true
      type: object
      required:
      - name
      - display_name
      - provider_type
      - provider_name
      - embedding_endpoint_type
      - embedding_model
      - embedding_dim
      title: EmbeddingModel
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ProviderCategory:
      type: string
      enum:
      - base
      - byok
      title: ProviderCategory
    ProviderType:
      type: string
      enum:
      - anthropic
      - azure
      - baseten
      - bedrock
      - cerebras
      - chatgpt_oauth
      - deepseek
      - fireworks
      - google_ai
      - google_vertex
      - groq
      - hugging-face
      - letta
      - lmstudio_openai
      - minimax
      - mistral
      - ollama
      - openai
      - together
      - vllm
      - sglang
      - openrouter
      - xai
      - zai
      - zai_coding
      title: ProviderType
    TextResponseFormat:
      properties:
        type:
          type: string
          const: text
          title: Type
          description: The type of the response format.
          default: text
      type: object
      title: TextResponseFormat
      description: Response format for plain text responses.
    JsonSchemaResponseFormat:
      properties:
        type:
          type: string
          const: json_schema
          title: Type
          description: The type of the response format.
          default: json_schema
        json_schema:
          additionalProperties: true
          type: object
          title: Json Schema
          description: The JSON schema of the response.
      type: object
      required:
      - json_schema
      title: JsonSchemaResponseFormat
      description: Response format for JSON schema-based responses.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer