Letta Chat API

openapi: 3.1.0
info:
  title: Letta Admin Chat 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: Chat
  description: Chat operations.
paths:
  /v1/chat/completions:
    post:
      tags:
      - Chat
      summary: Create Chat Completion
      description: 'Create a chat completion using a Letta agent (OpenAI-compatible).


        This endpoint provides full OpenAI API compatibility. The agent is selected based on:

        - The ''model'' parameter in the request (should contain an agent ID in format ''agent-...'')


        When streaming is enabled (stream=true), the response will be Server-Sent Events

        with ChatCompletionChunk objects.'
      operationId: create_chat_completion
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
            text/event-stream:
              description: Server-Sent Events stream (when stream=true)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChatCompletionContentPartInputAudioParam:
      properties:
        input_audio:
          $ref: '#/components/schemas/InputAudio'
        type:
          type: string
          const: input_audio
          title: Type
      type: object
      required:
      - input_audio
      - type
      title: ChatCompletionContentPartInputAudioParam
      description: Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).
    AnnotationURLCitation:
      properties:
        end_index:
          type: integer
          title: End Index
        start_index:
          type: integer
          title: Start Index
        title:
          type: string
          title: Title
        url:
          type: string
          title: Url
      additionalProperties: true
      type: object
      required:
      - end_index
      - start_index
      - title
      - url
      title: AnnotationURLCitation
      description: A URL citation when using web search.
    CompletionTokensDetails:
      properties:
        accepted_prediction_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Accepted Prediction Tokens
        audio_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Audio Tokens
        reasoning_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reasoning Tokens
        rejected_prediction_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rejected Prediction Tokens
      additionalProperties: true
      type: object
      title: CompletionTokensDetails
      description: Breakdown of tokens used in a completion.
    openai__types__chat__chat_completion_token_logprob__TopLogprob:
      properties:
        token:
          type: string
          title: Token
        bytes:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Bytes
        logprob:
          type: number
          title: Logprob
      additionalProperties: true
      type: object
      required:
      - token
      - logprob
      title: TopLogprob
    Audio:
      properties:
        id:
          type: string
          title: Id
      type: object
      required:
      - id
      title: Audio
      description: 'Data about a previous audio response from the model.

        [Learn more](https://platform.openai.com/docs/guides/audio).'
    ChatCompletionAudio:
      properties:
        id:
          type: string
          title: Id
        data:
          type: string
          title: Data
        expires_at:
          type: integer
          title: Expires At
        transcript:
          type: string
          title: Transcript
      additionalProperties: true
      type: object
      required:
      - id
      - data
      - expires_at
      - transcript
      title: ChatCompletionAudio
      description: 'If the audio output modality is requested, this object contains data

        about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).'
    File:
      properties:
        file:
          $ref: '#/components/schemas/FileFile'
        type:
          type: string
          const: file
          title: Type
      type: object
      required:
      - file
      - type
      title: File
      description: Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text generation.
    ChatCompletionContentPartImageParam:
      properties:
        image_url:
          $ref: '#/components/schemas/ImageURL'
        type:
          type: string
          const: image_url
          title: Type
      type: object
      required:
      - image_url
      - type
      title: ChatCompletionContentPartImageParam
      description: Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
    ChatCompletionSystemMessageParam:
      properties:
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
            type: array
          title: Content
        role:
          type: string
          const: system
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
      - content
      - role
      title: ChatCompletionSystemMessageParam
      description: 'Developer-provided instructions that the model should follow, regardless of

        messages sent by the user. With o1 models and newer, use `developer` messages

        for this purpose instead.'
    openai__types__chat__chat_completion__ChoiceLogprobs:
      properties:
        content:
          anyOf:
          - items:
              $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob'
            type: array
          - type: 'null'
          title: Content
        refusal:
          anyOf:
          - items:
              $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob'
            type: array
          - type: 'null'
          title: Refusal
      additionalProperties: true
      type: object
      title: ChoiceLogprobs
      description: Log probability information for the choice.
    ChatCompletionToolMessageParam:
      properties:
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
            type: array
          title: Content
        role:
          type: string
          const: tool
          title: Role
        tool_call_id:
          type: string
          title: Tool Call Id
      type: object
      required:
      - content
      - role
      - tool_call_id
      title: ChatCompletionToolMessageParam
    ChatCompletionFunctionMessageParam:
      properties:
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        name:
          type: string
          title: Name
        role:
          type: string
          const: function
          title: Role
      type: object
      required:
      - content
      - name
      - role
      title: ChatCompletionFunctionMessageParam
    PromptTokensDetails:
      properties:
        audio_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Audio Tokens
        cached_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cached Tokens
      additionalProperties: true
      type: object
      title: PromptTokensDetails
      description: Breakdown of tokens used in the prompt.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChatCompletionContentPartTextParam:
      properties:
        text:
          type: string
          title: Text
        type:
          type: string
          const: text
          title: Type
      type: object
      required:
      - text
      - type
      title: ChatCompletionContentPartTextParam
      description: Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation).
    openai__types__chat__chat_completion_token_logprob__ChatCompletionTokenLogprob:
      properties:
        token:
          type: string
          title: Token
        bytes:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Bytes
        logprob:
          type: number
          title: Logprob
        top_logprobs:
          items:
            $ref: '#/components/schemas/openai__types__chat__chat_completion_token_logprob__TopLogprob'
          type: array
          title: Top Logprobs
      additionalProperties: true
      type: object
      required:
      - token
      - logprob
      - top_logprobs
      title: ChatCompletionTokenLogprob
    openai__types__chat__chat_completion_message_function_tool_call_param__Function:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      type: object
      required:
      - arguments
      - name
      title: Function
      description: The function that the model called.
    ChatCompletionUserMessageParam:
      properties:
        content:
          anyOf:
          - type: string
          - items:
              anyOf:
              - $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              - $ref: '#/components/schemas/ChatCompletionContentPartImageParam'
              - $ref: '#/components/schemas/ChatCompletionContentPartInputAudioParam'
              - $ref: '#/components/schemas/File'
            type: array
          title: Content
        role:
          type: string
          const: user
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
      - content
      - role
      title: ChatCompletionUserMessageParam
      description: 'Messages sent by an end user, containing prompts or additional context

        information.'
    Choice:
      properties:
        finish_reason:
          type: string
          enum:
          - stop
          - length
          - tool_calls
          - content_filter
          - function_call
          title: Finish Reason
        index:
          type: integer
          title: Index
        logprobs:
          anyOf:
          - $ref: '#/components/schemas/openai__types__chat__chat_completion__ChoiceLogprobs'
          - type: 'null'
        message:
          $ref: '#/components/schemas/ChatCompletionMessage'
      additionalProperties: true
      type: object
      required:
      - finish_reason
      - index
      - message
      title: Choice
    Custom-Input:
      properties:
        input:
          type: string
          title: Input
        name:
          type: string
          title: Name
      type: object
      required:
      - input
      - name
      title: Custom
      description: The custom tool that the model called.
    ChatCompletionMessageCustomToolCall:
      properties:
        id:
          type: string
          title: Id
        custom:
          $ref: '#/components/schemas/Custom-Output'
        type:
          type: string
          const: custom
          title: Type
      additionalProperties: true
      type: object
      required:
      - id
      - custom
      - type
      title: ChatCompletionMessageCustomToolCall
      description: A call to a custom tool created by the model.
    ChatCompletion:
      properties:
        id:
          type: string
          title: Id
        choices:
          items:
            $ref: '#/components/schemas/Choice'
          type: array
          title: Choices
        created:
          type: integer
          title: Created
        model:
          type: string
          title: Model
        object:
          type: string
          const: chat.completion
          title: Object
        service_tier:
          anyOf:
          - type: string
            enum:
            - auto
            - default
            - flex
            - scale
            - priority
          - type: 'null'
          title: Service Tier
        system_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: System Fingerprint
        usage:
          anyOf:
          - $ref: '#/components/schemas/CompletionUsage'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - id
      - choices
      - created
      - model
      - object
      title: ChatCompletion
      description: Represents a chat completion response returned by model, based on the provided input.
    FileFile:
      properties:
        file_data:
          type: string
          title: File Data
        file_id:
          type: string
          title: File Id
        filename:
          type: string
          title: Filename
      type: object
      title: FileFile
    Annotation:
      properties:
        type:
          type: string
          const: url_citation
          title: Type
        url_citation:
          $ref: '#/components/schemas/AnnotationURLCitation'
      additionalProperties: true
      type: object
      required:
      - type
      - url_citation
      title: Annotation
      description: A URL citation when using web search.
    FunctionCall-Output:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      additionalProperties: true
      type: object
      required:
      - arguments
      - name
      title: FunctionCall
      description: 'Deprecated and replaced by `tool_calls`.


        The name and arguments of a function that should be called, as generated by the model.'
    ChatCompletionRequest:
      properties:
        model:
          type: string
          title: Model
          description: ID of the model to use
        messages:
          items:
            anyOf:
            - $ref: '#/components/schemas/ChatCompletionDeveloperMessageParam'
            - $ref: '#/components/schemas/ChatCompletionSystemMessageParam'
            - $ref: '#/components/schemas/ChatCompletionUserMessageParam'
            - $ref: '#/components/schemas/ChatCompletionAssistantMessageParam'
            - $ref: '#/components/schemas/ChatCompletionToolMessageParam'
            - $ref: '#/components/schemas/ChatCompletionFunctionMessageParam'
          type: array
          title: Messages
          description: Messages comprising the conversation so far
        temperature:
          anyOf:
          - type: number
            maximum: 2
            minimum: 0
          - type: 'null'
          title: Temperature
          description: Sampling temperature
        top_p:
          anyOf:
          - type: number
            maximum: 1
            minimum: 0
          - type: 'null'
          title: Top P
          description: Nucleus sampling parameter
        n:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: N
          description: Number of chat completion choices to generate
          default: 1
        stream:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Stream
          description: Whether to stream back partial progress
          default: false
        stop:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - type: 'null'
          title: Stop
          description: Sequences where the API will stop generating
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          description: Maximum number of tokens to generate
        presence_penalty:
          anyOf:
          - type: number
            maximum: 2
            minimum: -2
          - type: 'null'
          title: Presence Penalty
          description: Presence penalty
        frequency_penalty:
          anyOf:
          - type: number
            maximum: 2
            minimum: -2
          - type: 'null'
          title: Frequency Penalty
          description: Frequency penalty
        user:
          anyOf:
          - type: string
          - type: 'null'
          title: User
          description: A unique identifier representing your end-user
      type: object
      required:
      - model
      - messages
      title: ChatCompletionRequest
      description: OpenAI-compatible chat completion request - exactly matching OpenAI's schema.
    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
    InputAudio:
      properties:
        data:
          type: string
          title: Data
        format:
          type: string
          enum:
          - wav
          - mp3
          title: Format
      type: object
      required:
      - data
      - format
      title: InputAudio
    ImageURL:
      properties:
        url:
          type: string
          title: Url
        detail:
          type: string
          enum:
          - auto
          - low
          - high
          title: Detail
      type: object
      required:
      - url
      title: ImageURL
    Function-Output:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      additionalProperties: true
      type: object
      required:
      - arguments
      - name
      title: Function
      description: The function that the model called.
    CompletionUsage:
      properties:
        completion_tokens:
          type: integer
          title: Completion Tokens
        prompt_tokens:
          type: integer
          title: Prompt Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        completion_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/CompletionTokensDetails'
          - type: 'null'
        prompt_tokens_details:
          anyOf:
          - $ref: '#/components/schemas/PromptTokensDetails'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - completion_tokens
      - prompt_tokens
      - total_tokens
      title: CompletionUsage
      description: Usage statistics for the completion request.
    Custom-Output:
      properties:
        input:
          type: string
          title: Input
        name:
          type: string
          title: Name
      additionalProperties: true
      type: object
      required:
      - input
      - name
      title: Custom
      description: The custom tool that the model called.
    ChatCompletionMessageFunctionToolCallParam:
      properties:
        id:
          type: string
          title: Id
        function:
          $ref: '#/components/schemas/openai__types__chat__chat_completion_message_function_tool_call_param__Function'
        type:
          type: string
          const: function
          title: Type
      type: object
      required:
      - id
      - function
      - type
      title: ChatCompletionMessageFunctionToolCallParam
      description: A call to a function tool created by the model.
    ChatCompletionMessage:
      properties:
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        refusal:
          anyOf:
          - type: string
          - type: 'null'
          title: Refusal
        role:
          type: string
          const: assistant
          title: Role
        annotations:
          anyOf:
          - items:
              $ref: '#/components/schemas/Annotation'
            type: array
          - type: 'null'
          title: Annotations
        audio:
          anyOf:
          - $ref: '#/components/schemas/ChatCompletionAudio'
          - type: 'null'
        function_call:
          anyOf:
          - $ref: '#/components/schemas/FunctionCall-Output'
          - type: 'null'
        tool_calls:
          anyOf:
          - items:
              anyOf:
              - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall-Output'
              - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
      additionalProperties: true
      type: object
      required:
      - role
      title: ChatCompletionMessage
      description: A chat completion message generated by the model.
    FunctionCall-Input:
      properties:
        arguments:
          type: string
          title: Arguments
        name:
          type: string
          title: Name
      type: object
      required:
      - arguments
      - name
      title: FunctionCall
      description: 'Deprecated and replaced by `tool_calls`.


        The name and arguments of a function that should be called, as generated by the model.'
    ChatCompletionContentPartRefusalParam:
      properties:
        refusal:
          type: string
          title: Refusal
        type:
          type: string
          const: refusal
          title: Type
      type: object
      required:
      - refusal
      - type
      title: ChatCompletionContentPartRefusalParam
    ChatCompletionDeveloperMessageParam:
      properties:
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
            type: array
          title: Content
        role:
          type: string
          const: developer
          title: Role
        name:
          type: string
          title: Name
      type: object
      required:
      - content
      - role
      title: ChatCompletionDeveloperMessageParam
      description: 'Developer-provided instructions that the model should follow, regardless of

        messages sent by the user. With o1 models and newer, `developer` messages

        replace the previous `system` messages.'
    ChatCompletionMessageFunctionToolCall-Output:
      properties:
        id:
          type: string
          title: Id
        function:
          $ref: '#/components/schemas/Function-Output'
        type:
          type: string
          const: function
          title: Type
      additionalProperties: true
      type: object
      required:
      - id
      - function
      - type
      title: ChatCompletionMessageFunctionToolCall
      description: A call to a function tool created by the model.
    ChatCompletionAssistantMessageParam:
      properties:
        role:
          type: string
          const: assistant
          title: Role
        audio:
          anyOf:
          - $ref: '#/components/schemas/Audio'
          - type: 'null'
        content:
          anyOf:
          - type: string
          - items:
              anyOf:
              - $ref: '#/components/schemas/ChatCompletionContentPartTextParam'
              - $ref: '#/components/schemas/ChatCompletionContentPartRefusalParam'
            type: array
          - type: 'null'
          title: Content
        function_call:
          anyOf:
          - $ref: '#/components/schemas/FunctionCall-Input'
          - type: 'null'
        name:
          type: string
          title: Name
        refusal:
          anyOf:
          - type: string
          - type: 'null'
          title: Refusal
        tool_calls:
          items:
            anyOf:
            - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCallParam'
            - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCallParam'
          type: array
          title: Tool Calls
      type: object
      required:
      - role
      title: ChatCompletionAssistantMessageParam
      description: Messages sent by the model in response to user messages.
    ChatCompletionMessageCustomToolCallParam:
      properties:
        id:
          type: string
          title: Id
        custom:
          $ref: '#/components/schemas/Custom-Input'
        type:
          type: string
          const: custom
          title: Type
      type: object
      required:
      - id
      - custom
      - type
      title: ChatCompletionMessageCustomToolCallParam
      description: A call to a custom tool created by the model.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer