Letta Runs, Jobs and Steps API

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
       

# --- truncated at 32 KB (201 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta-ai/refs/heads/main/openapi/letta-ai-openapi.yml