openapi: 3.1.0
info:
  title: Letta Admin Environments 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: Environments
  description: Environment variables and configuration scoped to agents/tools.
paths:
  /v1/environments/register:
    post:
      description: Register a new listener connection and get connectionId for WebSocket
      summary: Register Environment
      tags:
      - Environments
      parameters: []
      operationId: environments.register
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                deviceId:
                  type: string
                connectionName:
                  type: string
                metadata:
                  type: object
                  properties:
                    os:
                      type: string
                    lettaCodeVersion:
                      type: string
                    nodeVersion:
                      type: string
                    workingDirectory:
                      type: string
                    gitBranch:
                      type: string
                  additionalProperties: true
              required:
              - deviceId
              - connectionName
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  connectionId:
                    type: string
                  wsUrl:
                    type: string
                required:
                - connectionId
                - wsUrl
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
  /v1/environments/{deviceId}:
    get:
      description: Get a specific environment connection by deviceId
      summary: Get Environment Connection
      tags:
      - Environments
      parameters:
      - name: deviceId
        in: path
        required: true
        schema:
          type: string
      operationId: environments.getConnection
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  connectionId:
                    type: string
                    nullable: true
                  deviceId:
                    type: string
                  connectionName:
                    type: string
                  organizationId:
                    type: string
                  userId:
                    type: string
                  apiKeyOwner:
                    type: string
                  podId:
                    type: string
                    nullable: true
                  connectedAt:
                    type: number
                    nullable: true
                  lastHeartbeat:
                    type: number
                    nullable: true
                  lastSeenAt:
                    type: number
                  firstSeenAt:
                    type: number
                  currentMode:
                    type: string
                    enum:
                    - default
                    - acceptEdits
                    - plan
                    - bypassPermissions
                  metadata:
                    type: object
                    properties:
                      os:
                        type: string
                      lettaCodeVersion:
                        type: string
                      nodeVersion:
                        type: string
                      workingDirectory:
                        type: string
                      gitBranch:
                        type: string
                    additionalProperties: true
                required:
                - id
                - connectionId
                - deviceId
                - connectionName
                - organizationId
                - podId
                - connectedAt
                - lastHeartbeat
                - lastSeenAt
                - firstSeenAt
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
  /v1/environments:
    get:
      description: List all active environment connections for the organization
      summary: List Environment Connections
      tags:
      - Environments
      parameters:
      - name: limit
        in: query
        schema:
          type: string
      - name: after
        in: query
        schema:
          type: string
      - name: userId
        in: query
        schema:
          type: string
      - name: onlineOnly
        in: query
        schema:
          type: string
      operationId: environments.listConnections
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        connectionId:
                          type: string
                          nullable: true
                        deviceId:
                          type: string
                        connectionName:
                          type: string
                        organizationId:
                          type: string
                        userId:
                          type: string
                        apiKeyOwner:
                          type: string
                        podId:
                          type: string
                          nullable: true
                        connectedAt:
                          type: number
                          nullable: true
                        lastHeartbeat:
                          type: number
                          nullable: true
                        lastSeenAt:
                          type: number
                        firstSeenAt:
                          type: number
                        currentMode:
                          type: string
                          enum:
                          - default
                          - acceptEdits
                          - plan
                          - bypassPermissions
                        metadata:
                          type: object
                          properties:
                            os:
                              type: string
                            lettaCodeVersion:
                              type: string
                            nodeVersion:
                              type: string
                            workingDirectory:
                              type: string
                            gitBranch:
                              type: string
                          additionalProperties: true
                      required:
                      - id
                      - connectionId
                      - deviceId
                      - connectionName
                      - organizationId
                      - podId
                      - connectedAt
                      - lastHeartbeat
                      - lastSeenAt
                      - firstSeenAt
                  hasNextPage:
                    type: boolean
                required:
                - connections
                - hasNextPage
  /v1/environments/{connectionId}/messages:
    post:
      description: Send a message to a specific environment connection
      summary: Send Message to Environment
      tags:
      - Environments
      parameters:
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      operationId: environments.sendMessage
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    oneOf:
                    - type: object
                      properties:
                        role:
                          type: string
                          enum:
                          - user
                        content:
                          oneOf:
                          - type: string
                          - type: array
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                  - text
                                text:
                                  type: string
                              required:
                              - type
                              - text
                        client_message_id:
                          type: string
                        otid:
                          type: string
                      required:
                      - role
                      - content
                      - client_message_id
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - approval
                        approvals:
                          type: array
                          items:
                            oneOf:
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                  - tool
                                tool_call_id:
                                  type: string
                                tool_return:
                                  oneOf:
                                  - type: string
                                  - type: array
                                    items:
                                      type: object
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                          - text
                                        text:
                                          type: string
                                      required:
                                      - type
                                      - text
                                status:
                                  type: string
                                  enum:
                                  - success
                                  - error
                                stdout:
                                  type: array
                                  items:
                                    type: string
                                  nullable: true
                                stderr:
                                  type: array
                                  items:
                                    type: string
                                  nullable: true
                              required:
                              - tool_call_id
                              - tool_return
                              - status
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                  - approval
                                approve:
                                  type: boolean
                                tool_call_id:
                                  type: string
                                reason:
                                  type: string
                                  nullable: true
                                updated_input:
                                  type: object
                                  additionalProperties: {}
                                  nullable: true
                              required:
                              - approve
                              - tool_call_id
                      required:
                      - type
                      - approvals
                agentId:
                  type: string
                conversationId:
                  type: string
                  nullable: true
              required:
              - messages
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                - success
                - message
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
        '503':
          description: '503'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
  /v1/environments/{id}:
    delete:
      description: Removes environment from list of environments
      summary: Delete Environment
      tags:
      - Environments
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      operationId: environments.deleteEnvironment
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
              nullable: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                - success
                - message
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                  message:
                    type: string
                required:
                - errorCode
                - message
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer