Letta API — Agents

naftiko: "1.0.0-alpha2"

info:
  label: "Letta API — Agents"
  description: >-
    Stateful agents — create, list, modify, export, and message agents with persistent memory and tools. 56 operations. Lead operation: List Agents. Self-contained Naftiko capability covering one Letta business surface.
  tags:
    - Letta
    - Stateful Agents
    - Agents
  created: "2026-05-08"
  modified: "2026-05-22"

binds:
  - namespace: env
    keys:
      LETTA_API_KEY: LETTA_API_KEY

capability:

  consumes:
    - type: http
      namespace: "letta-agents"
      baseUri: "https://api.letta.com"
      description: "Letta API — Agents business capability. Self-contained, no shared references."
      authentication:
        type: bearer
        token: "{{env.LETTA_API_KEY}}"
      resources:
        - name: "agents"
          path: "/v1/agents/"
          operations:
            - name: "list_agents"
              method: GET
              description: "List Agents"
              inputParameters:
                - name: "name"
                  in: query
                  type: string
                  required: false
                  description: "Name of the agent"
                - name: "tags"
                  in: query
                  type: string
                  required: false
                  description: "List of tags to filter agents by"
                - name: "match_all_tags"
                  in: query
                  type: boolean
                  required: false
                  description: "If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags."
                - name: "before"
                  in: query
                  type: string
                  required: false
                  description: "Cursor for pagination"
                - name: "after"
                  in: query
                  type: string
                  required: false
                  description: "Cursor for pagination"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "Limit for pagination"
                - name: "query_text"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by name"
                - name: "project_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by project ID - this will default to your default project on cloud"
                - name: "template_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by template ID"
                - name: "base_template_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by base template ID"
                - name: "identity_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by identity ID"
                - name: "identifier_keys"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by identifier keys"
                - name: "include_relationships"
                  in: query
                  type: string
                  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 reduci"
                - name: "include"
                  in: query
                  type: array
                  required: false
                  description: "Specify which relational fields to include in the response. No relationships are included by default."
                - name: "order"
                  in: query
                  type: string
                  required: false
                  description: "Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
                - name: "order_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by"
                - name: "ascending"
                  in: query
                  type: boolean
                  required: false
                  description: "Whether to sort agents oldest to newest (True) or newest to oldest (False, default)"
                - name: "sort_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by. Options: 'created_at' (default), 'last_run_completion'"
                - name: "last_stop_reason"
                  in: query
                  type: string
                  required: false
                  description: "Filter agents by their last stop reason."
                - name: "created_by_id"
                  in: query
                  type: string
                  required: false
                  description: "Filter agents by the user who created them."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "create_agent"
              method: POST
              description: "Create Agent"
              inputParameters:
                - name: "X-Project"
                  in: header
                  type: string
                  required: false
                  description: "The project slug to associate with the agent (cloud only)."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-count"
          path: "/v1/agents/count"
          operations:
            - name: "count_agents"
              method: GET
              description: "Count Agents"
              inputParameters:
                - name: "name"
                  in: query
                  type: string
                  required: false
                  description: "Name of the agent"
                - name: "tags"
                  in: query
                  type: string
                  required: false
                  description: "List of tags to filter agents by"
                - name: "match_all_tags"
                  in: query
                  type: boolean
                  required: false
                  description: "If True, only counts agents that match ALL given tags. Otherwise, counts agents that have ANY of the passed-in tags."
                - name: "query_text"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by name"
                - name: "project_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by project ID - this will default to your default project on cloud"
                - name: "template_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by template ID"
                - name: "base_template_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by base template ID"
                - name: "identity_id"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by identity ID"
                - name: "identifier_keys"
                  in: query
                  type: string
                  required: false
                  description: "Search agents by identifier keys"
                - name: "last_stop_reason"
                  in: query
                  type: string
                  required: false
                  description: "Filter agents by their last stop reason."
                - name: "created_by_id"
                  in: query
                  type: string
                  required: false
                  description: "Filter agents by the user who created them."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-export"
          path: "/v1/agents/{agent_id}/export"
          operations:
            - name: "export_agent"
              method: GET
              description: "Export Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "agent_id parameter"
                - name: "max_steps"
                  in: query
                  type: integer
                  required: false
                  description: "max_steps parameter"
                - name: "use_legacy_format"
                  in: query
                  type: boolean
                  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."
                - name: "conversation_id"
                  in: query
                  type: string
                  required: false
                  description: "Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history."
                - name: "scrub_messages"
                  in: query
                  type: boolean
                  required: false
                  description: "If True, excludes all messages from the export. Useful for sharing agent configs without conversation history."
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "export_agent_with_skills"
              method: POST
              description: "Export Agent with Skills"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "agent_id parameter"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-import"
          path: "/v1/agents/import"
          operations:
            - name: "import_agent"
              method: POST
              description: "Import Agent"
              inputParameters:
                - name: "x-override-embedding-model"
                  in: header
                  type: string
                  required: false
                  description: "x-override-embedding-model parameter"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-context"
          path: "/v1/agents/{agent_id}/context"
          operations:
            - name: "retrieve_agent_context_window"
              method: GET
              description: "Retrieve Agent Context Window"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "conversation_id"
                  in: query
                  type: string
                  required: false
                  description: "Conversation ID to get context window for. If provided, uses messages from this conversation."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id"
          path: "/v1/agents/{agent_id}"
          operations:
            - name: "modify_agent"
              method: PATCH
              description: "Modify Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "retrieve_agent"
              method: GET
              description: "Retrieve Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "include_relationships"
                  in: query
                  type: string
                  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 reduci"
                - name: "include"
                  in: query
                  type: array
                  required: false
                  description: "Specify which relational fields to include in the response. No relationships are included by default."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
            - name: "delete_agent"
              method: DELETE
              description: "Delete Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-tools"
          path: "/v1/agents/{agent_id}/tools"
          operations:
            - name: "list_tools_for_agent"
              method: GET
              description: "List Tools for Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "before"
                  in: query
                  type: string
                  required: false
                  description: "Tool ID cursor for pagination. Returns tools that come before this tool ID in the specified sort order"
                - name: "after"
                  in: query
                  type: string
                  required: false
                  description: "Tool ID cursor for pagination. Returns tools that come after this tool ID in the specified sort order"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "Maximum number of tools to return"
                - name: "order"
                  in: query
                  type: string
                  required: false
                  description: "Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest first"
                - name: "order_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-tools-attach-by-id"
          path: "/v1/agents/{agent_id}/tools/attach/{tool_id}"
          operations:
            - name: "attach_tool_to_agent"
              method: PATCH
              description: "Attach Tool to Agent"
              inputParameters:
                - name: "tool_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the tool in the format 'tool-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-tools-detach-by-id"
          path: "/v1/agents/{agent_id}/tools/detach/{tool_id}"
          operations:
            - name: "detach_tool_from_agent"
              method: PATCH
              description: "Detach Tool from Agent"
              inputParameters:
                - name: "tool_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the tool in the format 'tool-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-tools-approval-by-id"
          path: "/v1/agents/{agent_id}/tools/approval/{tool_name}"
          operations:
            - name: "modify_approval_for_tool"
              method: PATCH
              description: "Modify Approval for Tool"
              inputParameters:
                - name: "tool_name"
                  in: path
                  type: string
                  required: true
                  description: "tool_name parameter"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "requires_approval"
                  in: query
                  type: string
                  required: false
                  description: "Whether the tool requires approval before execution"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-tools-by-id-run"
          path: "/v1/agents/{agent_id}/tools/{tool_name}/run"
          operations:
            - name: "run_tool_for_agent"
              method: POST
              description: "Run Tool for Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "tool_name"
                  in: path
                  type: string
                  required: true
                  description: "tool_name parameter"
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "Request payload"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-sources-attach-by-id"
          path: "/v1/agents/{agent_id}/sources/attach/{source_id}"
          operations:
            - name: "attach_source_to_agent"
              method: PATCH
              description: "Attach Source"
              inputParameters:
                - name: "source_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the source in the format 'source-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-folders-attach-by-id"
          path: "/v1/agents/{agent_id}/folders/attach/{folder_id}"
          operations:
            - name: "attach_folder_to_agent"
              method: PATCH
              description: "Attach Folder to Agent"
              inputParameters:
                - name: "folder_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the source in the format 'source-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-sources-detach-by-id"
          path: "/v1/agents/{agent_id}/sources/detach/{source_id}"
          operations:
            - name: "detach_source_from_agent"
              method: PATCH
              description: "Detach Source"
              inputParameters:
                - name: "source_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the source in the format 'source-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-folders-detach-by-id"
          path: "/v1/agents/{agent_id}/folders/detach/{folder_id}"
          operations:
            - name: "detach_folder_from_agent"
              method: PATCH
              description: "Detach Folder from Agent"
              inputParameters:
                - name: "folder_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the source in the format 'source-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-files-close-all"
          path: "/v1/agents/{agent_id}/files/close-all"
          operations:
            - name: "close_all_files_for_agent"
              method: PATCH
              description: "Close All Files for Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-files-by-id-open"
          path: "/v1/agents/{agent_id}/files/{file_id}/open"
          operations:
            - name: "open_file_for_agent"
              method: PATCH
              description: "Open File for Agent"
              inputParameters:
                - name: "file_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the file in the format 'file-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-files-by-id-close"
          path: "/v1/agents/{agent_id}/files/{file_id}/close"
          operations:
            - name: "close_file_for_agent"
              method: PATCH
              description: "Close File for Agent"
              inputParameters:
                - name: "file_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the file in the format 'file-<uuid4>'"
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-sources"
          path: "/v1/agents/{agent_id}/sources"
          operations:
            - name: "list_agent_sources"
              method: GET
              description: "List Agent Sources"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "before"
                  in: query
                  type: string
                  required: false
                  description: "Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order"
                - name: "after"
                  in: query
                  type: string
                  required: false
                  description: "Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "Maximum number of sources to return"
                - name: "order"
                  in: query
                  type: string
                  required: false
                  description: "Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first"
                - name: "order_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-folders"
          path: "/v1/agents/{agent_id}/folders"
          operations:
            - name: "list_folders_for_agent"
              method: GET
              description: "List Folders for Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "before"
                  in: query
                  type: string
                  required: false
                  description: "Source ID cursor for pagination. Returns sources that come before this source ID in the specified sort order"
                - name: "after"
                  in: query
                  type: string
                  required: false
                  description: "Source ID cursor for pagination. Returns sources that come after this source ID in the specified sort order"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "Maximum number of sources to return"
                - name: "order"
                  in: query
                  type: string
                  required: false
                  description: "Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first"
                - name: "order_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by"
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "agents-by-id-files"
          path: "/v1/agents/{agent_id}/files"
          operations:
            - name: "list_files_for_agent"
              method: GET
              description: "List Files for Agent"
              inputParameters:
                - name: "agent_id"
                  in: path
                  type: string
                  required: true
                  description: "The ID of the agent in the format 'agent-<uuid4>'"
                - name: "before"
                  in: query
                  type: string
                  required: false
                  description: "File ID cursor for pagination. Returns files that come before this file ID in the specified sort order"
                - name: "after"
                  in: query
                  type: string
                  required: false
                  description: "File ID cursor for pagination. Returns files that come after this file ID in the specified sort order"
                - name: "limit"
                  in: query
                  type: string
                  required: false
                  description: "Maximum number of files to return"
                - name: "order"
                  in: query
                  type: string
                  required: false
                  description: "Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first"
                - name: "order_by"
                  in: query
                  type: string
                  required: false
                  description: "Field to sort by"
                - name: "cursor"
                  in: query
                  type: string
                  required: false
                  description: "Pagination cursor from previous response (deprecated, use before/after)"
                - name: "is_open"
                  in: query
                  type: string
                  required: false
                  description: "Filter by open status (true for open files, false for closed files)"
              outpu

# --- truncated at 32 KB (124 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/capabilities/letta-agents.yaml