openapi: 3.0.3
info:
  title: Letta API
  description: The Letta API creates and operates stateful AI agents whose memory - core context blocks
    and archival vector memory - persists across sessions. It configures the tools, data sources, identities,
    and multi-agent groups an agent uses, sends and streams messages to agents, and inspects the runs,
    jobs, and steps behind every agent response. The same OpenAPI-documented interface is served by the
    managed Letta Cloud API and by the open-source, self-hostable Letta server. All requests require a
    Bearer API key.
  version: 1.0.0
  contact:
    name: Letta
    url: https://www.letta.com
  license:
    name: Apache-2.0
    url: https://github.com/letta-ai/letta/blob/main/LICENSE
servers:
- url: https://api.letta.com/v1
  description: Letta Cloud
- url: http://localhost:8283/v1
  description: Self-hosted (default local port)
security:
- bearerAuth: []
tags:
- name: Agents
  description: Stateful agents and their lifecycle.
- name: Memory Blocks
  description: Core-memory blocks shared across agents, groups, and identities.
- name: Archival Memory
  description: Out-of-context long-term memory archives and passages.
- name: Tools
  description: Functions agents can call, including MCP-backed tools.
- name: MCP Servers
  description: Remote Model Context Protocol tool servers.
- name: Sources and Files
  description: Uploaded files and folders used for agent grounding and retrieval.
- name: Identities
  description: End users of a multi-tenant Letta deployment.
- name: Multi-Agent Groups
  description: Groups of agents coordinating around shared memory.
- name: Models and Providers
  description: Available models and configured BYOK model providers.
- name: Runs, Jobs and Steps
  description: Asynchronous execution history behind agent messages.
- name: Agent Templates
  description: Cloud-only versioned agent configuration templates.
- name: Chat Completions
  description: OpenAI-compatible chat completions backed by a Letta agent.
paths:
  /v1/agents/:
    get:
      tags:
      - Agents
      summary: List Agents
      description: Get a list of all agents.
      parameters:
      - name: name
        in: query
        required: false
        description: Name of the agent
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: List of tags to filter agents by
        schema:
          type: string
      - name: match_all_tags
        in: query
        required: false
        description: If True, only returns agents that match ALL given tags. Otherwise, return agents
          that have ANY of the passed-in tags.
        schema:
          type: boolean
          default: false
      - name: before
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Limit for pagination
        schema:
          type: string
          default: 50
      - name: query_text
        in: query
        required: false
        description: Search agents by name
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        description: Search agents by project ID - this will default to your default project on cloud
        schema:
          type: string
      - name: template_id
        in: query
        required: false
        description: Search agents by template ID
        schema:
          type: string
      - name: base_template_id
        in: query
        required: false
        description: Search agents by base template ID
        schema:
          type: string
      - name: identity_id
        in: query
        required: false
        description: Search agents by identity ID
        schema:
          type: string
      - name: identifier_keys
        in: query
        required: false
        description: Search agents by identifier keys
        schema:
          type: string
      - name: include_relationships
        in: query
        required: false
        description: Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in
          the response. If not provided, all relationships are loaded by default. Using this can optimize
          performance by reducing unnecessary joins.This is a legacy parameter, and no longer supported
          after 1.0.0 SDK versions.
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Specify which relational fields to include in the response. No relationships are
          included by default.
        schema:
          type: array
          default: []
      - name: order
        in: query
        required: false
        description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
          enum:
          - created_at
          - updated_at
          - last_run_completion
      - name: ascending
        in: query
        required: false
        description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default)
        schema:
          type: boolean
          default: false
      - name: sort_by
        in: query
        required: false
        description: 'Field to sort by. Options: ''created_at'' (default), ''last_run_completion'''
        schema:
          type: string
          default: created_at
      - name: last_stop_reason
        in: query
        required: false
        description: Filter agents by their last stop reason.
        schema:
          type: string
      - name: created_by_id
        in: query
        required: false
        description: Filter agents by the user who created them.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentState'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Agents
      summary: Create Agent
      description: Create an agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/count:
    get:
      tags:
      - Agents
      summary: Count Agents
      description: 'Get the total number of agents with optional filtering.

        Supports the same filters as list_agents for consistent querying.'
      parameters:
      - name: name
        in: query
        required: false
        description: Name of the agent
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: List of tags to filter agents by
        schema:
          type: string
      - name: match_all_tags
        in: query
        required: false
        description: If True, only counts agents that match ALL given tags. Otherwise, counts agents that
          have ANY of the passed-in tags.
        schema:
          type: boolean
          default: false
      - name: query_text
        in: query
        required: false
        description: Search agents by name
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        description: Search agents by project ID - this will default to your default project on cloud
        schema:
          type: string
      - name: template_id
        in: query
        required: false
        description: Search agents by template ID
        schema:
          type: string
      - name: base_template_id
        in: query
        required: false
        description: Search agents by base template ID
        schema:
          type: string
      - name: identity_id
        in: query
        required: false
        description: Search agents by identity ID
        schema:
          type: string
      - name: identifier_keys
        in: query
        required: false
        description: Search agents by identifier keys
        schema:
          type: string
      - name: last_stop_reason
        in: query
        required: false
        description: Filter agents by their last stop reason.
        schema:
          type: string
      - name: created_by_id
        in: query
        required: false
        description: Filter agents by the user who created them.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/agents/import:
    post:
      tags:
      - Agents
      summary: Import Agent
      description: 'Import a serialized agent file and recreate the agent(s) in the system.

        Returns the IDs of all imported agents.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/search:
    post:
      tags:
      - Agents
      summary: Search Deployed Agents
      description: Search deployed agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}:
    patch:
      tags:
      - Agents
      summary: Modify Agent
      description: Update an existing agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      tags:
      - Agents
      summary: Retrieve Agent
      description: Get the state of the agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: include_relationships
        in: query
        required: false
        description: Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in
          the response. If not provided, all relationships are loaded by default. Using this can optimize
          performance by reducing unnecessary joins.This is a legacy parameter, and no longer supported
          after 1.0.0 SDK versions.
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Specify which relational fields to include in the response. No relationships are
          included by default.
        schema:
          type: array
          default: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Agents
      summary: Delete Agent
      description: Delete an agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/export:
    get:
      tags:
      - Agents
      summary: Export Agent
      description: Export the serialized JSON representation of an agent, formatted with indentation.
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      - name: max_steps
        in: query
        required: false
        schema:
          type: integer
          default: 100
      - name: use_legacy_format
        in: query
        required: false
        description: If True, exports using the legacy single-agent 'v1' format with inline tools/blocks.
          If False, exports using the new multi-entity 'v2' format, with separate agents, tools, blocks,
          files, etc.
        schema:
          type: boolean
          default: false
      - name: conversation_id
        in: query
        required: false
        description: Conversation ID to export. If provided, uses messages from this conversation instead
          of the agent's global message history.
        schema:
          type: string
      - name: scrub_messages
        in: query
        required: false
        description: If True, excludes all messages from the export. Useful for sharing agent configs
          without conversation history.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Agents
      summary: Export Agent With Skills
      description: Export the serialized JSON representation of an agent with optional skills.
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/core-memory:
    get:
      tags:
      - Agents
      summary: Retrieve Agent Memory
      description: 'Retrieve the memory state of a specific agent.

        This endpoint fetches the current memory state of the agent identified by the user ID and agent
        ID.'
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/core-memory/blocks:
    get:
      tags:
      - Agents
      summary: List Blocks For Agent
      description: Retrieve the core memory blocks of a specific agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come before this block ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come after this block ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of blocks to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}:
    patch:
      tags:
      - Agents
      summary: Attach Block To Agent
      description: Attach a core memory block to an agent.
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/core-memory/blocks/detach/{block_id}:
    patch:
      tags:
      - Agents
      summary: Detach Block From Agent
      description: Detach a core memory block from an agent.
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/core-memory/blocks/{block_label}:
    get:
      tags:
      - Agents
      summary: Retrieve Block For Agent
      description: Retrieve a core memory block from an agent.
      parameters:
      - name: block_label
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Agents
      summary: Modify Block For Agent
      description: Updates a core memory block of an agent.
      parameters:
      - name: block_label
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlockRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/archival-memory:
    get:
      tags:
      - Agents
      summary: List Passages
      description: Retrieve the memories in an agent's archival memory store (paginated query).
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Unique ID of the memory to start the query range at.
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Unique ID of the memory to end the query range at.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: How many results to include in the response.
        schema:
          type: string
          default: 100
      - name: search
        in: query
        required: false
        description: Search passages by text
        schema:
          type: string
      - name: ascending
        in: query
        required: false
        description: Whether to sort passages oldest to newest (True, default) or newest to oldest (False)
        schema:
          type: string
          default: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Passage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Agents
      summary: Create Passage
      description: Insert a memory into an agent's archival memory store.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Passage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/archival-memory/search:
    get:
      tags:
      - Agents
      summary: Search Archival Memory
      description: Search archival memory using semantic (embedding-based) search with optional temporal
        filtering.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: query
        in: query
        required: true
        description: String to search for using semantic similarity
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: Optional list of tags to filter search results
        schema:
          type: string
      - name: tag_match_mode
        in: query
        required: false
        description: How to match tags - 'any' to match passages with any of the tags, 'all' to match
          only passages with all tags
        schema:
          type: string
          default: any
          enum:
          - any
          - all
      - name: top_k
        in: query
        required: false
        description: Maximum number of results to return. Uses system default if not specified
        schema:
          type: string
      - name: start_datetime
        in: query
        required: false
        description: Filter results to passages created after this datetime
        schema:
          type: string
      - name: end_datetime
        in: query
        required: false
        description: Filter results to passages created before this datetime
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/archival-memory/{memory_id}:
    delete:
      tags:
      - Agents
      summary: Delete Passage
      description: Delete a memory from an agent's archival memory store.
      parameters:
      - name: memory_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/archives/attach/{archive_id}:
    patch:
      tags:
      - Agents
      summary: Attach Archive To Agent
      description: Attach an archive to an agent.
      parameters:
      - name: archive_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/archives/detach/{archive_id}:
    patch:
      tags:
      - Agents
      summary: Detach Archive From Agent
      description: Detach an archive from an agent.
      parameters:
      - name: archive_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages:
    get:
      tags:
      - Agents
      summary: List Messages
      description: Retrieve message history for an agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come before this message
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come after this message ID
          in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: group_id
        in: query
        required: false
        description: Group ID to filter messages by.
        schema:
          type: string
      - name: conversation_id
        in: query
        required: false
        description: Conversation ID to filter messages by.
        schema:
          type: string
      - name: use_assistant_message
        in: query
        required: false
        description: Whether to use assistant messages
        schema:
          type: boolean
          default: true
      - name: assistant_message_tool_name
        in: query
        required: false
        description: The name of the designated message tool.
        schema:
          type: string
          default: send_message
      - name: assistant_message_tool_kwarg
        in: query
        required: false
        description: The name of the message argument.
        schema:
          type: string
          default: message
      - name: include_err
        in: query
        required: false
        description: Whether to include error messages and error statuses. For debugging purposes only.
        schema:
          type: string
      - name: include_return_message_types
        in: query
        required: false
        description: Message types to include in response. When null, all message types are returned.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LettaMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Agents
      summary: Send Message
      description: 'Process a user message and return the agent''s response.

        This endpoint accepts a message from a user and processes it through the agent.'
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LettaMessage'
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages/async:
    post:
      tags:
      - Agents
      summary: Send Message Async
      description: 'Asynchronously process a user message and return a run object.

        The actual processing happens in the background, and the status can be checked using the run ID.'
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages/stream:
    post:
      tags:
      - Agents
      summary: Send Message Streaming
      description: Process a user message and return the agent's response.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LettaMessage'
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages/cancel:
    post:
      tags:
      - Agents
      summary: Cancel Message
      description: Cancel runs associated with an agent. If run_ids are passed in, cancel those in particular.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages/preview-raw-payload:
    post:
      tags:
      - Agents
      summary: Preview Model Request
      description: Inspect the raw LLM request payload without sending it.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/messages/{message_id}:
    patch:
      tags:
      - Agents
      summary: Modify Message
      description: Update the details of a message associated with an agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: message_id
        in: path
        required: true
        description: The ID of the message in the format 'message-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/reset-messages:
    patch:
      tags:
      - Agents
      summary: Reset Messages
      description: Resets the messages for an agent
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/summarize:
    post:
      tags:
      - Agents
      summary: Summarize Messages
      description: Summarize an agent's conversation history.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/sources:
    get:
      tags:
      - Agents
      summary: List Agent Sources
      description: Get the sources associated with an agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Source ID cursor for pagination. Returns sources that come before this source ID
          in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Source ID cursor for pagination. Returns sources that come after this source ID in
          the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of sources to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/sources/attach/{source_id}:
    patch:
      tags:
      - Agents
      summary: Attach Source
      description: Attach a source to an agent.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/sources/detach/{source_id}:
    patch:
      tags:
      - Agents
      summary: Detach Source
      description: Detach a source from an agent.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/tools:
    get:
      tags:
      - Agents
      summary: List Tools For Agent
      description: Get tools from an existing agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Tool ID cursor for pagination. Returns tools that come before this tool ID in the
          specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Tool ID cursor for pagination. Returns tools that come after this tool ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of tools to return
        schema:
          type: string
          default: 10
      - name: order
        in: query
        required: false
        description: Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/tools/attach/{tool_id}:
    patch:
      tags:
      - Agents
      summary: Attach Tool To Agent
      description: Attach a tool to an agent.
      parameters:
      - name: tool_id
        in: path
        required: true
        description: The ID of the tool in the format 'tool-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/tools/detach/{tool_id}:
    patch:
      tags:
      - Agents
      summary: Detach Tool From Agent
      description: Detach a tool from an agent.
      parameters:
      - name: tool_id
        in: path
        required: true
        description: The ID of the tool in the format 'tool-<uuid4>'
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/identities/attach/{identity_id}:
    patch:
      tags:
      - Agents
      summary: Attach Identity To Agent
      description: Attach an identity to an agent.
      parameters:
      - name: identity_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/identities/detach/{identity_id}:
    patch:
      tags:
      - Agents
      summary: Detach Identity From Agent
      description: Detach an identity from an agent.
      parameters:
      - name: identity_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/agents/{agent_id}/groups:
    get:
      tags:
      - Agents
      summary: List Groups For Agent
      description: Lists the groups for an agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: manager_type
        in: query
        required: false
        description: Manager type to filter groups by
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Group ID cursor for pagination. Returns groups that come before this group ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Group ID cursor for pagination. Returns groups that come after this group ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of groups to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for groups by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/agents/{agent_id}/context:
    get:
      tags:
      - Agents
      summary: Retrieve Agent Context Window
      description: Retrieve the context window of a specific agent.
      parameters:
      - name: agent_id
        in: path
        required: true
        description: The ID of the agent in the format 'agent-<uuid4>'
        schema:
          type: string
      - name: conversation_id
        in: query
        required: false
        description: Conversation ID to get context window for. If provided, uses messages from this conversation.
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/blocks/:
    get:
      tags:
      - Memory Blocks
      summary: List Blocks
      description: List Blocks
      parameters:
      - name: label
        in: query
        required: false
        description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
        schema:
          type: string
      - name: templates_only
        in: query
        required: false
        description: Whether to include only templates
        schema:
          type: boolean
          default: false
      - name: name
        in: query
        required: false
        description: Name filter (alphanumeric, spaces, hyphens, underscores)
        schema:
          type: string
      - name: identity_id
        in: query
        required: false
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      - name: identifier_keys
        in: query
        required: false
        description: Search agents by identifier keys
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        description: Search blocks by project id
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: List of tags to filter blocks by
        schema:
          type: string
      - name: match_all_tags
        in: query
        required: false
        description: If True, only returns blocks that match ALL given tags. Otherwise, return blocks
          that have ANY of the passed-in tags.
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        required: false
        description: Number of blocks to return
        schema:
          type: string
          default: 50
      - name: before
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come before this block ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come after this block ID in the
          specified sort order
        schema:
          type: string
      - name: order
        in: query
        required: false
        description: Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: label_search
        in: query
        required: false
        description: Search blocks by label. If provided, returns blocks whose label matches the search
          query. This is a full-text search on block labels.
        schema:
          type: string
      - name: description_search
        in: query
        required: false
        description: Search blocks by description. If provided, returns blocks whose description matches
          the search query. This is a full-text search on block descriptions.
        schema:
          type: string
      - name: value_search
        in: query
        required: false
        description: Search blocks by value. If provided, returns blocks whose value matches the search
          query. This is a full-text search on block values.
        schema:
          type: string
      - name: connected_to_agents_count_gt
        in: query
        required: false
        description: Filter blocks by the number of connected agents. If provided, returns blocks that
          have more than this number of connected agents.
        schema:
          type: string
      - name: connected_to_agents_count_lt
        in: query
        required: false
        description: Filter blocks by the number of connected agents. If provided, returns blocks that
          have less than this number of connected agents.
        schema:
          type: string
      - name: connected_to_agents_count_eq
        in: query
        required: false
        description: Filter blocks by the exact number of connected agents. If provided, returns blocks
          that have exactly this number of connected agents.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Memory Blocks
      summary: Create Block
      description: Create Block
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlockRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/blocks/count:
    get:
      tags:
      - Memory Blocks
      summary: Count Blocks
      description: 'Count all blocks with optional filtering.

        Supports the same filters as list_blocks for consistent querying.'
      parameters:
      - name: label
        in: query
        required: false
        description: Label to include (alphanumeric, hyphens, underscores, forward slashes)
        schema:
          type: string
      - name: templates_only
        in: query
        required: false
        description: Whether to include only templates
        schema:
          type: boolean
          default: false
      - name: name
        in: query
        required: false
        description: Name filter (alphanumeric, spaces, hyphens, underscores)
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: List of tags to filter blocks by
        schema:
          type: string
      - name: match_all_tags
        in: query
        required: false
        description: If True, only counts blocks that match ALL given tags. Otherwise, counts blocks that
          have ANY of the passed-in tags.
        schema:
          type: boolean
          default: false
      - name: project_id
        in: query
        required: false
        description: Search blocks by project id
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/blocks/{block_id}:
    patch:
      tags:
      - Memory Blocks
      summary: Modify Block
      description: Modify Block
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlockRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Memory Blocks
      summary: Delete Block
      description: Delete Block
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      tags:
      - Memory Blocks
      summary: Retrieve Block
      description: Retrieve Block
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/blocks/{block_id}/agents:
    get:
      tags:
      - Memory Blocks
      summary: List Agents For Block
      description: 'Retrieves all agents associated with the specified block.

        Raises a 404 if the block does not exist.'
      parameters:
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come before this agent ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of agents to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: include_relationships
        in: query
        required: false
        description: Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in
          the response. If not provided, all relationships are loaded by default. Using this can optimize
          performance by reducing unnecessary joins.This is a legacy parameter, and no longer supported
          after 1.0.0 SDK versions.
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Specify which relational fields to include in the response. No relationships are
          included by default.
        schema:
          type: array
          default: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/blocks/{block_id}/identities/attach/{identity_id}:
    patch:
      tags:
      - Memory Blocks
      summary: Attach Identity To Block
      description: Attach an identity to a block.
      parameters:
      - name: identity_id
        in: path
        required: true
        schema:
          type: string
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/blocks/{block_id}/identities/detach/{identity_id}:
    patch:
      tags:
      - Memory Blocks
      summary: Detach Identity From Block
      description: Detach an identity from a block.
      parameters:
      - name: identity_id
        in: path
        required: true
        schema:
          type: string
      - name: block_id
        in: path
        required: true
        description: The ID of the block in the format 'block-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/archives/:
    post:
      tags:
      - Archival Memory
      summary: Create Archive
      description: Create a new archive.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Archive'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      tags:
      - Archival Memory
      summary: List Archives
      description: Get a list of all archives for the current organization with optional filters and pagination.
      parameters:
      - name: before
        in: query
        required: false
        description: Archive ID cursor for pagination. Returns archives that come before this archive
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Archive ID cursor for pagination. Returns archives that come after this archive ID
          in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of archives to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for archives by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: name
        in: query
        required: false
        description: Filter by archive name (exact match)
        schema:
          type: string
      - name: agent_id
        in: query
        required: false
        description: Only archives attached to this agent ID
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Archive'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/archives/{archive_id}:
    get:
      tags:
      - Archival Memory
      summary: Retrieve Archive
      description: Get a single archive by its ID.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Archive'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Archival Memory
      summary: Modify Archive
      description: Update an existing archive's name and/or description.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Archive'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Archival Memory
      summary: Delete Archive
      description: Delete an archive by its ID.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/archives/{archive_id}/agents:
    get:
      tags:
      - Archival Memory
      summary: List Agents For Archive
      description: Get a list of agents that have access to an archive with pagination support.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come before this agent ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of agents to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: include
        in: query
        required: false
        description: Specify which relational fields to include in the response. No relationships are
          included by default.
        schema:
          type: array
          default: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/archives/{archive_id}/passages:
    post:
      tags:
      - Archival Memory
      summary: Create Passage In Archive
      description: Create a new passage in an archive.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Passage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/archives/{archive_id}/passages/batch:
    post:
      tags:
      - Archival Memory
      summary: Create Passages In Archive
      description: Create multiple passages in an archive.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Passage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/archives/{archive_id}/passages/{passage_id}:
    delete:
      tags:
      - Archival Memory
      summary: Delete Passage From Archive
      description: Delete a passage from an archive.
      parameters:
      - name: archive_id
        in: path
        required: true
        description: The ID of the archive in the format 'archive-<uuid4>'
        schema:
          type: string
      - name: passage_id
        in: path
        required: true
        description: The ID of the passage in the format 'passage-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/tools/:
    get:
      tags:
      - Tools
      summary: List Tools
      description: Get a list of all tools available to agents.
      parameters:
      - name: before
        in: query
        required: false
        description: Tool ID cursor for pagination. Returns tools that come before this tool ID in the
          specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Tool ID cursor for pagination. Returns tools that come after this tool ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of tools to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: name
        in: query
        required: false
        description: Filter by single tool name
        schema:
          type: string
      - name: names
        in: query
        required: false
        description: Filter by specific tool names
        schema:
          type: string
      - name: tool_ids
        in: query
        required: false
        description: Filter by specific tool IDs - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Search tool names (case-insensitive partial match)
        schema:
          type: string
      - name: tool_types
        in: query
        required: false
        description: Filter by tool type(s) - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: exclude_tool_types
        in: query
        required: false
        description: Tool type(s) to exclude - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: return_only_letta_tools
        in: query
        required: false
        description: Return only tools with tool_type starting with 'letta_'
        schema:
          type: string
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Tools
      summary: Create Tool
      description: Create a new tool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      tags:
      - Tools
      summary: Upsert Tool
      description: Create or update a tool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/count:
    get:
      tags:
      - Tools
      summary: Count Tools
      description: Get a count of all tools available to agents belonging to the org of the user.
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: names
        in: query
        required: false
        description: Filter by specific tool names
        schema:
          type: string
      - name: tool_ids
        in: query
        required: false
        description: Filter by specific tool IDs - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Search tool names (case-insensitive partial match)
        schema:
          type: string
      - name: tool_types
        in: query
        required: false
        description: Filter by tool type(s) - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: exclude_tool_types
        in: query
        required: false
        description: Tool type(s) to exclude - accepts repeated params or comma-separated values
        schema:
          type: string
      - name: return_only_letta_tools
        in: query
        required: false
        description: Count only tools with tool_type starting with 'letta_'
        schema:
          type: string
          default: false
      - name: exclude_letta_tools
        in: query
        required: false
        description: Exclude built-in Letta tools from the count
        schema:
          type: string
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/tools/add-base-tools:
    post:
      tags:
      - Tools
      summary: Upsert Base Tools
      description: Upsert base tools
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/run:
    post:
      tags:
      - Tools
      summary: Run Tool From Source
      description: Attempt to build a tool from source, then run it on the provided arguments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/search:
    post:
      tags:
      - Tools
      summary: Search Tools
      description: Search tools using semantic search.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/{tool_id}:
    delete:
      tags:
      - Tools
      summary: Delete Tool
      description: Delete a tool by name
      parameters:
      - name: tool_id
        in: path
        required: true
        description: The ID of the tool in the format 'tool-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      tags:
      - Tools
      summary: Retrieve Tool
      description: Get a tool by ID
      parameters:
      - name: tool_id
        in: path
        required: true
        description: The ID of the tool in the format 'tool-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Tools
      summary: Modify Tool
      description: Update an existing tool
      parameters:
      - name: tool_id
        in: path
        required: true
        description: The ID of the tool in the format 'tool-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/mcp/servers:
    get:
      tags:
      - Tools
      summary: List Mcp Servers
      description: Get a list of all configured MCP servers
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/McpServerConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Tools
      summary: Add Mcp Server To Config
      description: Add a new MCP server to the Letta MCP server config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/mcp/servers/connect:
    post:
      tags:
      - Tools
      summary: Connect Mcp Server
      description: 'Connect to an MCP server with support for OAuth via SSE.

        Returns a stream of events handling authorization state and exchange if OAuth is required.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/mcp/servers/test:
    post:
      tags:
      - Tools
      summary: Test Mcp Server
      description: 'Test connection to an MCP server without adding it.

        Returns the list of available tools if successful.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/mcp/servers/{mcp_server_name}:
    patch:
      tags:
      - Tools
      summary: Update Mcp Server
      description: Update an existing MCP server configuration
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Tools
      summary: Delete Mcp Server From Config
      description: Delete a MCP server configuration
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/tools/mcp/servers/{mcp_server_name}/resync:
    post:
      tags:
      - Tools
      summary: Resync Mcp Server Tools
      description: 'Resync tools for an MCP server by:

        1. Fetching current tools from the MCP server

        2. Deleting tools that no longer exist on the server

        3. Updating schemas for existing tools

        4. Adding new tools from the server'
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tools/mcp/servers/{mcp_server_name}/tools:
    get:
      tags:
      - Tools
      summary: List Mcp Tools By Server
      description: Get a list of all tools for a specific MCP server
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/tools/mcp/servers/{mcp_server_name}/tools/{tool_name}/execute:
    post:
      tags:
      - Tools
      summary: Execute Mcp Tool
      description: 'Execute a specific MCP tool from a configured server.

        Returns the tool execution result.'
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        schema:
          type: string
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/mcp-servers/:
    post:
      tags:
      - MCP Servers
      summary: Create Mcp Server
      description: Add a new MCP server to the Letta MCP server config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      tags:
      - MCP Servers
      summary: List Mcp Servers
      description: Get a list of all configured MCP servers
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/McpServerConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/mcp-servers/{mcp_server_id}:
    get:
      tags:
      - MCP Servers
      summary: Retrieve Mcp Server
      description: Get a specific MCP server
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - MCP Servers
      summary: Delete Mcp Server
      description: Delete an MCP server by its ID
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - MCP Servers
      summary: Update Mcp Server
      description: Update an existing MCP server configuration
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/mcp-servers/{mcp_server_id}/refresh:
    patch:
      tags:
      - MCP Servers
      summary: Refresh Mcp Server Tools
      description: 'Refresh tools for an MCP server by:

        1. Fetching current tools from the MCP server

        2. Deleting tools that no longer exist on the server

        3. Updating schemas for existing tools

        4. Adding new tools from the server'
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/mcp-servers/{mcp_server_id}/tools:
    get:
      tags:
      - MCP Servers
      summary: List Tools For Mcp Server
      description: Get a list of all tools for a specific MCP server
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}:
    get:
      tags:
      - MCP Servers
      summary: Retrieve Mcp Tool
      description: Get a specific MCP tool by its ID
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/mcp-servers/{mcp_server_id}/tools/{tool_id}/run:
    post:
      tags:
      - MCP Servers
      summary: Run Mcp Tool
      description: Execute a specific MCP tool
      parameters:
      - name: mcp_server_id
        in: path
        required: true
        schema:
          type: string
      - name: tool_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/sources/:
    get:
      tags:
      - Sources and Files
      summary: List Sources
      description: List all data sources created by a user.
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Sources and Files
      summary: Create Source
      description: Create a new data source.
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/sources/count:
    get:
      tags:
      - Sources and Files
      summary: Count Sources
      description: Count all data sources created by a user.
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/sources/metadata:
    get:
      tags:
      - Sources and Files
      summary: Get Sources Metadata
      description: Get aggregated metadata for all sources in an organization.
      parameters:
      - name: include_detailed_per_source_metadata
        in: query
        required: false
        schema:
          type: boolean
          default: false
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/sources/name/{source_name}:
    get:
      tags:
      - Sources and Files
      summary: Get Source Id By Name
      description: Get a source by name
      parameters:
      - name: source_name
        in: path
        required: true
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}:
    get:
      tags:
      - Sources and Files
      summary: Retrieve Source
      description: Get all sources
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Sources and Files
      summary: Modify Source
      description: Update the name or documentation of an existing data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Sources and Files
      summary: Delete Source
      description: Delete a data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}/agents:
    get:
      tags:
      - Sources and Files
      summary: Get Agents For Source
      description: Get all agent IDs that have the specified source attached.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}/files:
    get:
      tags:
      - Sources and Files
      summary: List Source Files
      description: List paginated files associated with a data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Number of files to return
        schema:
          type: integer
          default: 1000
      - name: after
        in: query
        required: false
        description: Pagination cursor to fetch the next set of results
        schema:
          type: string
      - name: include_content
        in: query
        required: false
        description: Whether to include full file content
        schema:
          type: boolean
          default: false
      - name: check_status_updates
        in: query
        required: false
        description: Whether to check and update file processing status (from the vector db service).
          If False, will not fetch and update the status, which may lead to performance gains.
        schema:
          type: boolean
          default: true
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}/files/{file_id}:
    get:
      tags:
      - Sources and Files
      summary: Get File Metadata
      description: Retrieve metadata for a specific file by its ID.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: file_id
        in: path
        required: true
        description: The ID of the file in the format 'file-<uuid4>'
        schema:
          type: string
      - name: include_content
        in: query
        required: false
        description: Whether to include full file content
        schema:
          type: boolean
          default: false
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}/passages:
    get:
      tags:
      - Sources and Files
      summary: List Source Passages
      description: List all passages associated with a data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Message after which to retrieve the returned messages.
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Message before which to retrieve the returned messages.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to retrieve.
        schema:
          type: integer
          default: 100
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/sources/{source_id}/upload:
    post:
      tags:
      - Sources and Files
      summary: Upload File To Source
      description: Upload a file to a data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: duplicate_handling
        in: query
        required: false
        description: How to handle duplicate filenames
        schema:
          type: string
          default: suffix
      - name: name
        in: query
        required: false
        description: Optional custom name to override the uploaded file's name
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/sources/{source_id}/{file_id}:
    delete:
      tags:
      - Sources and Files
      summary: Delete File From Source
      description: Delete a data source.
      parameters:
      - name: source_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: file_id
        in: path
        required: true
        description: The ID of the file in the format 'file-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/folders/:
    get:
      tags:
      - Sources and Files
      summary: List Folders
      description: List all data folders created by a user.
      parameters:
      - name: before
        in: query
        required: false
        description: Folder ID cursor for pagination. Returns folders that come before this folder ID
          in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Folder ID cursor for pagination. Returns folders that come after this folder ID in
          the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of folders to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for folders by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: name
        in: query
        required: false
        description: Folder name to filter by
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Sources and Files
      summary: Create Folder
      description: Create a new data folder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/folders/count:
    get:
      tags:
      - Sources and Files
      summary: Count Folders
      description: Count all data folders created by a user.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/folders/{folder_id}:
    get:
      tags:
      - Sources and Files
      summary: Retrieve Folder
      description: Get a folder by ID
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Sources and Files
      summary: Modify Folder
      description: Update the name or documentation of an existing data folder.
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Sources and Files
      summary: Delete Folder
      description: Delete a data folder.
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/folders/{folder_id}/upload:
    post:
      tags:
      - Sources and Files
      summary: Upload File To Folder
      description: Upload a file to a data folder.
      parameters:
      - name: folder_id
        in: path
        required: true
        description: The ID of the source in the format 'source-<uuid4>'
        schema:
          type: string
      - name: duplicate_handling
        in: query
        required: false
        description: How to handle duplicate filenames
        schema:
          type: string
          default: suffix
      - name: name
        in: query
        required: false
        description: Optional custom name to override the uploaded file's name
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/identities/:
    get:
      tags:
      - Identities
      summary: List Identities
      description: Get a list of all identities in the database
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        description: '[DEPRECATED: Use X-Project-Id header instead] Filter identities by project ID'
        schema:
          type: string
      - name: identifier_key
        in: query
        required: false
        schema:
          type: string
      - name: identity_type
        in: query
        required: false
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Identity ID cursor for pagination. Returns identities that come before this identity
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Identity ID cursor for pagination. Returns identities that come after this identity
          ID in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of identities to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for identities by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Identities
      summary: Create Identity
      description: Create Identity
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      tags:
      - Identities
      summary: Upsert Identity
      description: Upsert Identity
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/identities/count:
    get:
      tags:
      - Identities
      summary: Count Identities
      description: Get count of all identities for a user
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/identities/{identity_id}:
    get:
      tags:
      - Identities
      summary: Retrieve Identity
      description: Retrieve Identity
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Identities
      summary: Modify Identity
      description: Modify Identity
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Identities
      summary: Delete Identity
      description: Delete an identity by its identifier key
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/identities/{identity_id}/agents:
    get:
      tags:
      - Identities
      summary: List Agents For Identity
      description: Get all agents associated with the specified identity.
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come before this agent ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Agent ID cursor for pagination. Returns agents that come after this agent ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of agents to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: include
        in: query
        required: false
        description: Specify which relational fields to include in the response. No relationships are
          included by default.
        schema:
          type: array
          default: []
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/identities/{identity_id}/blocks:
    get:
      tags:
      - Identities
      summary: List Blocks For Identity
      description: Get all blocks associated with the specified identity.
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come before this block ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Block ID cursor for pagination. Returns blocks that come after this block ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of blocks to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/identities/{identity_id}/properties:
    put:
      tags:
      - Identities
      summary: Upsert Properties For Identity
      description: Upsert Properties For Identity
      parameters:
      - name: identity_id
        in: path
        required: true
        description: The ID of the identity in the format 'identity-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/groups/:
    get:
      tags:
      - Multi-Agent Groups
      summary: List Groups
      description: Fetch all multi-agent groups matching query.
      parameters:
      - name: manager_type
        in: query
        required: false
        description: Search groups by manager type
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Group ID cursor for pagination. Returns groups that come before this group ID in
          the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Group ID cursor for pagination. Returns groups that come after this group ID in the
          specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of groups to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for groups by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: project_id
        in: query
        required: false
        description: Search groups by project id
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Multi-Agent Groups
      summary: Create Group
      description: Create a new multi-agent group with the specified configuration.
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/groups/count:
    get:
      tags:
      - Multi-Agent Groups
      summary: Count Groups
      description: Get the count of all groups associated with a given user.
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/groups/{group_id}:
    get:
      tags:
      - Multi-Agent Groups
      summary: Retrieve Group
      description: Retrieve the group by id.
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Multi-Agent Groups
      summary: Modify Group
      description: Create a new multi-agent group with the specified configuration.
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Multi-Agent Groups
      summary: Delete Group
      description: Delete a multi-agent group.
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/groups/{group_id}/blocks/attach/{block_id}:
    patch:
      tags:
      - Multi-Agent Groups
      summary: Attach Block To Group
      description: 'Attach a block to a group.

        This will add the block to the group and all agents within the group.'
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/groups/{group_id}/blocks/detach/{block_id}:
    patch:
      tags:
      - Multi-Agent Groups
      summary: Detach Block From Group
      description: 'Detach a block from a group.

        This will remove the block from the group and all agents within the group.'
      parameters:
      - name: block_id
        in: path
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/groups/{group_id}/messages:
    get:
      tags:
      - Multi-Agent Groups
      summary: List Group Messages
      description: Retrieve message history for an agent.
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come before this message
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come after this message ID
          in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to retrieve
        schema:
          type: string
          default: 10
      - name: order
        in: query
        required: false
        description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: use_assistant_message
        in: query
        required: false
        description: Whether to use assistant messages
        schema:
          type: boolean
          default: true
      - name: assistant_message_tool_name
        in: query
        required: false
        description: The name of the designated message tool.
        schema:
          type: string
          default: send_message
      - name: assistant_message_tool_kwarg
        in: query
        required: false
        description: The name of the message argument.
        schema:
          type: string
          default: message
      - name: include_return_message_types
        in: query
        required: false
        description: Message types to include in response. When null, all message types are returned.
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LettaMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/groups/{group_id}/reset-messages:
    patch:
      tags:
      - Multi-Agent Groups
      summary: Reset Group Messages
      description: Delete the group messages for all agents that are part of the multi-agent group.
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group in the format 'group-<uuid4>'
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/models/:
    get:
      tags:
      - Models and Providers
      summary: List Llm Models
      description: List available LLM models using the asynchronous implementation for improved performance.
      parameters:
      - name: provider_category
        in: query
        required: false
        schema:
          type: string
      - name: provider_name
        in: query
        required: false
        schema:
          type: string
      - name: provider_type
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Model'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/models/embedding:
    get:
      tags:
      - Models and Providers
      summary: List Embedding Models
      description: List available embedding models using the asynchronous implementation for improved
        performance.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Model'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/providers/:
    get:
      tags:
      - Models and Providers
      summary: List Providers
      description: Get a list of all custom providers.
      parameters:
      - name: before
        in: query
        required: false
        description: Provider ID cursor for pagination. Returns providers that come before this provider
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Provider ID cursor for pagination. Returns providers that come after this provider
          ID in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of providers to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for providers by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: name
        in: query
        required: false
        description: Filter providers by name
        schema:
          type: string
      - name: provider_type
        in: query
        required: false
        description: Filter providers by type
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Models and Providers
      summary: Create Provider
      description: Create a new custom provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/providers/check:
    post:
      tags:
      - Models and Providers
      summary: Check Provider
      description: Verify the API key and additional parameters for a provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/providers/{provider_id}:
    get:
      tags:
      - Models and Providers
      summary: Retrieve Provider
      description: Get a provider by ID.
      parameters:
      - name: provider_id
        in: path
        required: true
        description: The ID of the provider in the format 'provider-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Models and Providers
      summary: Modify Provider
      description: Update an existing custom provider.
      parameters:
      - name: provider_id
        in: path
        required: true
        description: The ID of the provider in the format 'provider-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Models and Providers
      summary: Delete Provider
      description: Delete an existing custom provider.
      parameters:
      - name: provider_id
        in: path
        required: true
        description: The ID of the provider in the format 'provider-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/providers/{provider_id}/check:
    post:
      tags:
      - Models and Providers
      summary: Check Existing Provider
      description: Verify the API key and additional parameters for an existing provider.
      parameters:
      - name: provider_id
        in: path
        required: true
        description: The ID of the provider in the format 'provider-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/providers/{provider_id}/refresh:
    patch:
      tags:
      - Models and Providers
      summary: Refresh Provider Models
      description: 'Refresh models for a BYOK provider by querying the provider''s API.

        Adds new models and removes ones no longer available.'
      parameters:
      - name: provider_id
        in: path
        required: true
        description: The ID of the provider in the format 'provider-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/runs/:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Runs
      description: List all runs.
      parameters:
      - name: agent_id
        in: query
        required: false
        description: The unique identifier of the agent associated with the run.
        schema:
          type: string
      - name: agent_ids
        in: query
        required: false
        description: The unique identifiers of the agents associated with the run. Deprecated in favor
          of agent_id field.
        schema:
          type: string
      - name: statuses
        in: query
        required: false
        description: Filter runs by status. Can specify multiple statuses.
        schema:
          type: string
      - name: background
        in: query
        required: false
        description: If True, filters for runs that were created in background mode.
        schema:
          type: string
      - name: stop_reason
        in: query
        required: false
        description: Filter runs by stop reason.
        schema:
          type: string
      - name: conversation_id
        in: query
        required: false
        description: Filter runs by conversation ID.
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Run ID cursor for pagination. Returns runs that come before this run ID in the specified
          sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Run ID cursor for pagination. Returns runs that come after this run ID in the specified
          sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of runs to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: active
        in: query
        required: false
        description: Filter for active runs.
        schema:
          type: boolean
          default: false
      - name: ascending
        in: query
        required: false
        description: Whether to sort agents oldest to newest (True) or newest to oldest (False, default).
          Deprecated in favor of order field.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Run'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/runs/active:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Active Runs
      description: List all active runs.
      parameters:
      - name: agent_id
        in: query
        required: false
        description: The unique identifier of the agent associated with the run.
        schema:
          type: string
      - name: background
        in: query
        required: false
        description: If True, filters for runs that were created in background mode.
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Run'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/runs/{run_id}:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Run
      description: Get the status of a run.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Runs, Jobs and Steps
      summary: Delete Run
      description: Delete a run by its run_id.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/runs/{run_id}/messages:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Messages For Run
      description: Get response messages associated with a run.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come before this message
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come after this message ID
          in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LettaMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/runs/{run_id}/metrics:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Metrics For Run
      description: Get run metrics by run ID.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/runs/{run_id}/steps:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Steps For Run
      description: Get steps associated with a run with filtering options.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Step'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/runs/{run_id}/stream:
    post:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Stream For Run
      description: Retrieve Stream For Run
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/runs/{run_id}/trace:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Trace For Run
      description: Retrieve OTEL trace spans for a run.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of spans to return
        schema:
          type: integer
          default: 1000
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/runs/{run_id}/usage:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Usage For Run
      description: Get usage statistics for a run.
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/jobs/:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Jobs
      description: List all jobs.
      parameters:
      - name: source_id
        in: query
        required: false
        description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the
          source.'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Job ID cursor for pagination. Returns jobs that come before this job ID in the specified
          sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Job ID cursor for pagination. Returns jobs that come after this job ID in the specified
          sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of jobs to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for jobs by creation time. 'asc' for oldest first, 'desc' for newest first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: active
        in: query
        required: false
        description: Filter for active jobs.
        schema:
          type: boolean
          default: false
      - name: ascending
        in: query
        required: false
        description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False).
          Deprecated in favor of order field.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/jobs/active:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Active Jobs
      description: List all active jobs.
      parameters:
      - name: source_id
        in: query
        required: false
        description: 'Deprecated: Use `folder_id` parameter instead. Only list jobs associated with the
          source.'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Cursor for pagination
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Limit for pagination
        schema:
          type: string
          default: 50
      - name: ascending
        in: query
        required: false
        description: Whether to sort jobs oldest to newest (True, default) or newest to oldest (False)
        schema:
          type: boolean
          default: true
      deprecated: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/jobs/{job_id}:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Job
      description: Get the status of a job.
      parameters:
      - name: job_id
        in: path
        required: true
        description: The ID of the job in the format 'job-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Runs, Jobs and Steps
      summary: Delete Job
      description: Delete a job by its job_id.
      parameters:
      - name: job_id
        in: path
        required: true
        description: The ID of the job in the format 'job-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/jobs/{job_id}/cancel:
    patch:
      tags:
      - Runs, Jobs and Steps
      summary: Cancel Job
      description: Cancel a job by its job_id.
      parameters:
      - name: job_id
        in: path
        required: true
        description: The ID of the job in the format 'job-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/steps/:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Steps
      description: List steps with optional pagination and date filters.
      parameters:
      - name: before
        in: query
        required: false
        description: Return steps before this step ID
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Return steps after this step ID
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of steps to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: created_at
      - name: start_date
        in: query
        required: false
        description: Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
        schema:
          type: string
      - name: end_date
        in: query
        required: false
        description: Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
        schema:
          type: string
      - name: model
        in: query
        required: false
        description: Filter by the name of the model used for the step
        schema:
          type: string
      - name: agent_id
        in: query
        required: false
        description: Filter by the ID of the agent that performed the step
        schema:
          type: string
      - name: trace_ids
        in: query
        required: false
        description: Filter by trace ids returned by the server
        schema:
          type: string
      - name: feedback
        in: query
        required: false
        description: Filter by feedback
        schema:
          type: string
      - name: has_feedback
        in: query
        required: false
        description: Filter by whether steps have feedback (true) or not (false)
        schema:
          type: string
      - name: tags
        in: query
        required: false
        description: Filter by tags
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        description: Filter by the project ID that is associated with the step (cloud only).
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Step'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/steps/{step_id}:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Step
      description: Get a step by ID.
      parameters:
      - name: step_id
        in: path
        required: true
        description: The ID of the step in the format 'step-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/steps/{step_id}/feedback:
    patch:
      tags:
      - Runs, Jobs and Steps
      summary: Modify Feedback For Step
      description: Modify feedback for a given step.
      parameters:
      - name: step_id
        in: path
        required: true
        description: The ID of the step in the format 'step-<uuid4>'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/steps/{step_id}/messages:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: List Messages For Step
      description: List messages for a given step.
      parameters:
      - name: step_id
        in: path
        required: true
        description: The ID of the step in the format 'step-<uuid4>'
        schema:
          type: string
      - name: before
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come before this message
          ID in the specified sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Message ID cursor for pagination. Returns messages that come after this message ID
          in the specified sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of messages to return
        schema:
          type: string
          default: 100
      - name: order
        in: query
        required: false
        description: Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest
          first
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Sort by field
        schema:
          type: string
          default: created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/steps/{step_id}/metrics:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Metrics For Step
      description: Get step metrics by step ID.
      parameters:
      - name: step_id
        in: path
        required: true
        description: The ID of the step in the format 'step-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/steps/{step_id}/trace:
    get:
      tags:
      - Runs, Jobs and Steps
      summary: Retrieve Trace For Step
      description: Retrieve Trace For Step
      parameters:
      - name: step_id
        in: path
        required: true
        description: The ID of the step in the format 'step-<uuid4>'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/templates:
    get:
      tags:
      - Agent Templates
      summary: List templates (Cloud-only)
      description: List all templates
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: string
      - name: exact
        in: query
        required: false
        description: Whether to search for an exact name match
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      - name: version
        in: query
        required: false
        description: Specify the version you want to return, otherwise will return the latest version
        schema:
          type: string
      - name: template_id
        in: query
        required: false
        schema:
          type: string
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: project_slug
        in: query
        required: false
        schema:
          type: string
      - name: project_id
        in: query
        required: false
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - updated_at
          - created_at
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Template'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Agent Templates
      summary: Create template (Cloud-only)
      description: Creates a new template from an existing agent or agent file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/templates/{project_id}:
    post:
      tags:
      - Agent Templates
      summary: Create template (Cloud-only)
      description: Creates a new template from an existing agent or agent file
      parameters:
      - name: project_id
        in: path
        required: true
        description: The project id
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/templates/{project_id}/{name}/versions:
    get:
      tags:
      - Agent Templates
      summary: List template versions (Cloud-only)
      description: List all versions of a specific template
      parameters:
      - name: project_id
        in: path
        required: true
        description: The project id
        schema:
          type: string
      - name: name
        in: path
        required: true
        description: The template name (without version)
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/templates/{project_id}/{template_version}/agents:
    post:
      tags:
      - Agent Templates
      summary: Create Agents From Template
      description: Creates an Agent or multiple Agents from a template
      parameters:
      - name: project_id
        in: path
        required: true
        description: The project id
        schema:
          type: string
      - name: template_version
        in: path
        required: true
        description: The template version, formatted as {template-name}:{version-number} or {template-name}:latest.
          This endpoint is not available for self-hosted Letta.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/chat/completions:
    post:
      tags:
      - Chat Completions
      summary: Create Chat Completion
      description: Create a chat completion using a Letta agent (OpenAI-compatible).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/voice-beta/{agent_id}/chat/completions:
    post:
      tags:
      - Voice
      summary: Create Voice Chat Completions
      description: 'DEPRECATED: This voice-beta endpoint has been deprecated.'
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              description: Server-Sent Events stream
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/tags/:
    get:
      tags:
      - Tag
      summary: List Tags
      description: Get the list of all tags (from agents and blocks) that have been created.
      parameters:
      - name: before
        in: query
        required: false
        description: Tag cursor for pagination. Returns tags that come before this tag in the specified
          sort order
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Tag cursor for pagination. Returns tags that come after this tag in the specified
          sort order
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of tags to return
        schema:
          type: string
          default: 50
      - name: order
        in: query
        required: false
        description: Sort order for tags. 'asc' for alphabetical order, 'desc' for reverse alphabetical
          order
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: order_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          default: name
      - name: query_text
        in: query
        required: false
        description: Filter tags by text search. Deprecated, please use name field instead
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Filter tags by name
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key created at https://app.letta.com/api-keys, passed as `Authorization: Bearer
        YOUR_API_KEY`.'
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HTTPValidationError'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
              msg:
                type: string
              type:
                type: string
    AgentState:
      type: object
      description: A Letta stateful agent, including its memory, tools, sources, and model configuration.
      properties:
        id:
          type: string
          example: agent-123e4567-e89b-42d3-8456-426614174000
        name:
          type: string
        agent_type:
          type: string
        system:
          type: string
        description:
          type: string
        model:
          type: string
        embedding:
          type: string
        llm_config:
          type: object
          additionalProperties: true
        embedding_config:
          type: object
          additionalProperties: true
        memory:
          type: object
          additionalProperties: true
        blocks:
          type: array
          items:
            type: object
            additionalProperties: true
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        sources:
          type: array
          items:
            type: object
            additionalProperties: true
        tags:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateAgentRequest:
      type: object
      properties:
        name:
          type: string
        system:
          type: string
        agent_type:
          type: string
          enum:
          - memgpt_agent
          - react_agent
          - workflow_agent
          - sleeptime_agent
        model:
          type: string
          example: openai/gpt-4o
        embedding:
          type: string
          example: openai/text-embedding-3-small
        memory_blocks:
          type: array
          items:
            type: object
            additionalProperties: true
        tools:
          type: array
          items:
            type: string
        tool_ids:
          type: array
          items:
            type: string
        source_ids:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        include_base_tools:
          type: boolean
          default: true
    Block:
      type: object
      description: A core-memory block - a labeled, always-in-context chunk of agent memory.
      properties:
        id:
          type: string
        label:
          type: string
          example: persona
        value:
          type: string
        limit:
          type: integer
          description: Character limit for the block value.
        is_template:
          type: boolean
        template_name:
          type: string
        read_only:
          type: boolean
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        hidden:
          type: boolean
        tags:
          type: array
          items:
            type: string
    CreateBlockRequest:
      type: object
      required:
      - label
      - value
      properties:
        label:
          type: string
        value:
          type: string
        limit:
          type: integer
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Archive:
      type: object
      description: An agent's out-of-context, searchable long-term memory archive.
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        vector_db_provider:
          type: string
        embedding_config:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Passage:
      type: object
      description: A single unit of archival memory - a chunk of text with its embedding.
      properties:
        id:
          type: string
        text:
          type: string
        archive_id:
          type: string
        source_id:
          type: string
        file_id:
          type: string
        file_name:
          type: string
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Tool:
      type: object
      description: A function an agent can call.
      properties:
        id:
          type: string
        name:
          type: string
        tool_type:
          type: string
        description:
          type: string
        source_type:
          type: string
          example: python
        source_code:
          type: string
        json_schema:
          type: object
          additionalProperties: true
        args_json_schema:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        pip_requirements:
          type: array
          items:
            type: object
            additionalProperties: true
        default_requires_approval:
          type: boolean
    CreateToolRequest:
      type: object
      required:
      - source_code
      properties:
        source_code:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        source_type:
          type: string
          default: python
        json_schema:
          type: object
          additionalProperties: true
    McpServerConfig:
      type: object
      description: A configured remote MCP (Model Context Protocol) tool server. Shape varies by transport
        (stdio, SSE, or Streamable HTTP).
      properties:
        id:
          type: string
        server_name:
          type: string
        type:
          type: string
          enum:
          - sse
          - stdio
          - streamable_http
        server_url:
          type: string
          format: uri
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        custom_headers:
          type: object
          additionalProperties:
            type: string
    Source:
      type: object
      description: A data source (also exposed as a folder) holding uploaded files for agent grounding.
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        instructions:
          type: string
        embedding_config:
          type: object
          additionalProperties: true
        vector_db_provider:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    CreateSourceRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        instructions:
          type: string
        embedding:
          type: string
    FileMetadata:
      type: object
      properties:
        id:
          type: string
        file_name:
          type: string
        source_id:
          type: string
        file_type:
          type: string
        file_size:
          type: integer
        processing_status:
          type: string
        created_at:
          type: string
          format: date-time
    Identity:
      type: object
      description: An end user of a multi-tenant Letta deployment.
      properties:
        id:
          type: string
        identifier_key:
          type: string
        name:
          type: string
        identity_type:
          type: string
          enum:
          - org
          - user
          - other
        project_id:
          type: string
        agent_ids:
          type: array
          items:
            type: string
        block_ids:
          type: array
          items:
            type: string
        properties:
          type: array
          items:
            type: object
            additionalProperties: true
    CreateIdentityRequest:
      type: object
      required:
      - identifier_key
      - name
      - identity_type
      properties:
        identifier_key:
          type: string
        name:
          type: string
        identity_type:
          type: string
          enum:
          - org
          - user
          - other
        agent_ids:
          type: array
          items:
            type: string
        block_ids:
          type: array
          items:
            type: string
    Group:
      type: object
      description: A multi-agent group coordinating several agents around shared memory.
      properties:
        id:
          type: string
        description:
          type: string
        manager_type:
          type: string
          enum:
          - round_robin
          - supervisor
          - dynamic
          - sleeptime
          - voice_sleeptime
        manager_agent_id:
          type: string
        agent_ids:
          type: array
          items:
            type: string
        shared_block_ids:
          type: array
          items:
            type: string
        termination_token:
          type: string
        max_turns:
          type: integer
    CreateGroupRequest:
      type: object
      required:
      - agent_ids
      - manager_config
      properties:
        description:
          type: string
        agent_ids:
          type: array
          items:
            type: string
        shared_block_ids:
          type: array
          items:
            type: string
        manager_config:
          type: object
          additionalProperties: true
    Model:
      type: object
      description: An LLM or embedding model available on Letta.
      properties:
        handle:
          type: string
          example: openai/gpt-4o
        name:
          type: string
        display_name:
          type: string
        provider_type:
          type: string
        provider_name:
          type: string
        model_type:
          type: string
        context_window:
          type: integer
        max_tokens:
          type: integer
    Provider:
      type: object
      description: A bring-your-own-key model provider configured on a Letta deployment.
      properties:
        id:
          type: string
        name:
          type: string
        provider_type:
          type: string
          example: anthropic
        provider_category:
          type: string
          enum:
          - base
          - byok
        api_key:
          type: string
          writeOnly: true
        base_url:
          type: string
        region:
          type: string
        updated_at:
          type: string
          format: date-time
        last_synced:
          type: string
          format: date-time
    CreateProviderRequest:
      type: object
      required:
      - name
      - provider_type
      - api_key
      properties:
        name:
          type: string
        provider_type:
          type: string
        api_key:
          type: string
        base_url:
          type: string
    Run:
      type: object
      description: An asynchronous execution of an agent turn.
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - created
          - running
          - completed
          - failed
          - cancelled
        agent_id:
          type: string
        background:
          type: boolean
        stop_reason:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        ttft_ns:
          type: integer
          description: Time to first token, in nanoseconds.
        total_duration_ns:
          type: integer
    Job:
      type: object
      description: A background job, such as a file-processing or batch operation.
      properties:
        id:
          type: string
        status:
          type: string
        job_type:
          type: string
        agent_id:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    Step:
      type: object
      description: A single model call within a run.
      properties:
        id:
          type: string
        run_id:
          type: string
        agent_id:
          type: string
        provider_name:
          type: string
        model:
          type: string
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        stop_reason:
          type: string
        trace_id:
          type: string
    Template:
      type: object
      description: A Cloud-only versioned agent configuration used to deploy new agents.
      properties:
        name:
          type: string
        project_id:
          type: string
        version:
          type: integer
        agent_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    LettaMessage:
      type: object
      description: A single message in an agent conversation (user, assistant, tool call/return, or reasoning).
      properties:
        id:
          type: string
        message_type:
          type: string
          enum:
          - user_message
          - assistant_message
          - reasoning_message
          - tool_call_message
          - tool_return_message
          - system_message
        content:
          type: string
        date:
          type: string
          format: date-time
    CreateMessageRequest:
      type: object
      required:
      - messages
      properties:
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                - user
                - system
              content:
                type: string
        stream_steps:
          type: boolean
          default: false
        stream_tokens:
          type: boolean
          default: false