Letta · Capability
Letta API — Folders
Folders — organize agents and resources into folders. 14 operations. Lead operation: Count Folders. Self-contained Naftiko capability covering one Letta business surface.
Letta API — Folders is a Naftiko capability published by Letta, one of 36 capabilities the APIs.io network indexes for this provider. It bundles 14 operations across the GET, DELETE, POST, and PATCH methods rooted at /v1/folders.
The capability includes 9 read-only operations and 5 state-changing operations. Lead operation: Count Folders. Can be deployed as a REST endpoint, MCP tool, or Agent Skill via Naftiko.
Tagged areas include Letta, Stateful Agents, and Folders.
What You Can Do
GET
Count_folders
— Count Folders
/v1/folders/count
GET
Retrieve_folder
— Retrieve Folder
/v1/folders/{folder-id}
PATCH
Modify_folder
— Modify Folder
/v1/folders/{folder-id}
DELETE
Delete_folder
— Delete Folder
/v1/folders/{folder-id}
GET
Get_folder_by_name
— Get Folder by Name
/v1/folders/name/{folder-name}
GET
Retrieve_metadata
— Retrieve Metadata
/v1/folders/metadata
GET
List_folders
— List Folders
/v1/folders/
POST
Create_folder
— Create Folder
/v1/folders/
POST
Upload_file_to_folder
— Upload File to Folder
/v1/folders/{folder-id}/upload
GET
List_agents_for_folder
— List Agents for Folder
/v1/folders/{folder-id}/agents
GET
List_folder_passages
— List Folder Passages
/v1/folders/{folder-id}/passages
GET
List_files_for_folder
— List Files for Folder
/v1/folders/{folder-id}/files
GET
Retrieve_file
— Retrieve File
/v1/folders/{folder-id}/files/{file-id}
DELETE
Delete_file_from_folder
— Delete File from Folder
/v1/folders/{folder-id}/{file-id}
MCP Tools
count-folders
Count Folders
read-only
idempotent
retrieve-folder
Retrieve Folder
read-only
idempotent
modify-folder
Modify Folder
idempotent
delete-folder
Delete Folder
idempotent
get-folder-name
Get Folder by Name
read-only
idempotent
retrieve-metadata
Retrieve Metadata
read-only
idempotent
list-folders
List Folders
read-only
idempotent
create-folder
Create Folder
upload-file-folder
Upload File to Folder
list-agents-folder
List Agents for Folder
read-only
idempotent
list-folder-passages
List Folder Passages
read-only
idempotent
list-files-folder
List Files for Folder
read-only
idempotent
retrieve-file
Retrieve File
read-only
idempotent
delete-file-folder
Delete File from Folder
idempotent
Capability Spec
naftiko: "1.0.0-alpha2"
info:
label: "Letta API — Folders"
description: >-
Folders — organize agents and resources into folders. 14 operations. Lead operation: Count Folders. Self-contained Naftiko capability covering one Letta business surface.
tags:
- Letta
- Stateful Agents
- Folders
created: "2026-05-08"
modified: "2026-05-22"
binds:
- namespace: env
keys:
LETTA_API_KEY: LETTA_API_KEY
capability:
consumes:
- type: http
namespace: "letta-folders"
baseUri: "https://api.letta.com"
description: "Letta API — Folders business capability. Self-contained, no shared references."
authentication:
type: bearer
token: "{{env.LETTA_API_KEY}}"
resources:
- name: "folders-count"
path: "/v1/folders/count"
operations:
- name: "count_folders"
method: GET
description: "Count Folders"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id"
path: "/v1/folders/{folder_id}"
operations:
- name: "retrieve_folder"
method: GET
description: "Retrieve Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "modify_folder"
method: PATCH
description: "Modify Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "delete_folder"
method: DELETE
description: "Delete Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-name-by-id"
path: "/v1/folders/name/{folder_name}"
operations:
- name: "get_folder_by_name"
method: GET
description: "Get Folder by Name"
inputParameters:
- name: "folder_name"
in: path
type: string
required: true
description: "folder_name parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-metadata"
path: "/v1/folders/metadata"
operations:
- name: "retrieve_metadata"
method: GET
description: "Retrieve Metadata"
inputParameters:
- name: "include_detailed_per_source_metadata"
in: query
type: boolean
required: false
description: "include_detailed_per_source_metadata parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders"
path: "/v1/folders/"
operations:
- name: "list_folders"
method: GET
description: "List Folders"
inputParameters:
- name: "before"
in: query
type: string
required: false
description: "Folder ID cursor for pagination. Returns folders that come before this folder ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Folder ID cursor for pagination. Returns folders that come after this folder ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of folders to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for folders 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: "name"
in: query
type: string
required: false
description: "Folder name to filter by"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "create_folder"
method: POST
description: "Create Folder"
inputParameters:
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id-upload"
path: "/v1/folders/{folder_id}/upload"
operations:
- name: "upload_file_to_folder"
method: POST
description: "Upload File to Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "duplicate_handling"
in: query
type: string
required: false
description: "How to handle duplicate filenames"
- name: "name"
in: query
type: string
required: false
description: "Optional custom name to override the uploaded file's name"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id-agents"
path: "/v1/folders/{folder_id}/agents"
operations:
- name: "list_agents_for_folder"
method: GET
description: "List Agents for Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "before"
in: query
type: string
required: false
description: "Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of agents to return"
- 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"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id-passages"
path: "/v1/folders/{folder_id}/passages"
operations:
- name: "list_folder_passages"
method: GET
description: "List Folder Passages"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "before"
in: query
type: string
required: false
description: "Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Passage ID cursor for pagination. Returns passages that come after this passage ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of passages to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for passages 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: "folders-by-id-files"
path: "/v1/folders/{folder_id}/files"
operations:
- name: "list_files_for_folder"
method: GET
description: "List Files for Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<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: "include_content"
in: query
type: boolean
required: false
description: "Whether to include full file content"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id-files-by-id"
path: "/v1/folders/{folder_id}/files/{file_id}"
operations:
- name: "retrieve_file"
method: GET
description: "Retrieve File"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "file_id"
in: path
type: string
required: true
description: "The ID of the file in the format 'file-<uuid4>'"
- name: "include_content"
in: query
type: boolean
required: false
description: "Whether to include full file content"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "folders-by-id-by-id"
path: "/v1/folders/{folder_id}/{file_id}"
operations:
- name: "delete_file_from_folder"
method: DELETE
description: "Delete File from Folder"
inputParameters:
- name: "folder_id"
in: path
type: string
required: true
description: "The ID of the source in the format 'source-<uuid4>'"
- name: "file_id"
in: path
type: string
required: true
description: "The ID of the file in the format 'file-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
exposes:
- type: rest
namespace: "letta-folders-rest"
port: 8080
description: "REST adapter for Letta API — Folders. One Spectral-compliant resource per consumed operation."
resources:
- path: "/v1/folders/count"
name: "folders-count"
description: "REST surface for folders-count."
operations:
- method: GET
name: "count_folders"
description: "Count Folders"
call: "letta-folders.count_folders"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}"
name: "folders-by-id"
description: "REST surface for folders-by-id."
operations:
- method: GET
name: "retrieve_folder"
description: "Retrieve Folder"
call: "letta-folders.retrieve_folder"
with:
"folder_id": "rest.folder_id"
outputParameters:
- type: object
mapping: "$."
- method: PATCH
name: "modify_folder"
description: "Modify Folder"
call: "letta-folders.modify_folder"
with:
"folder_id": "rest.folder_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: DELETE
name: "delete_folder"
description: "Delete Folder"
call: "letta-folders.delete_folder"
with:
"folder_id": "rest.folder_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/name/{folder-name}"
name: "folders-name-by-id"
description: "REST surface for folders-name-by-id."
operations:
- method: GET
name: "get_folder_by_name"
description: "Get Folder by Name"
call: "letta-folders.get_folder_by_name"
with:
"folder_name": "rest.folder_name"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/metadata"
name: "folders-metadata"
description: "REST surface for folders-metadata."
operations:
- method: GET
name: "retrieve_metadata"
description: "Retrieve Metadata"
call: "letta-folders.retrieve_metadata"
with:
"include_detailed_per_source_metadata": "rest.include_detailed_per_source_metadata"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/"
name: "folders"
description: "REST surface for folders."
operations:
- method: GET
name: "list_folders"
description: "List Folders"
call: "letta-folders.list_folders"
with:
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
"name": "rest.name"
outputParameters:
- type: object
mapping: "$."
- method: POST
name: "create_folder"
description: "Create Folder"
call: "letta-folders.create_folder"
with:
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/upload"
name: "folders-by-id-upload"
description: "REST surface for folders-by-id-upload."
operations:
- method: POST
name: "upload_file_to_folder"
description: "Upload File to Folder"
call: "letta-folders.upload_file_to_folder"
with:
"folder_id": "rest.folder_id"
"duplicate_handling": "rest.duplicate_handling"
"name": "rest.name"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/agents"
name: "folders-by-id-agents"
description: "REST surface for folders-by-id-agents."
operations:
- method: GET
name: "list_agents_for_folder"
description: "List Agents for Folder"
call: "letta-folders.list_agents_for_folder"
with:
"folder_id": "rest.folder_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/passages"
name: "folders-by-id-passages"
description: "REST surface for folders-by-id-passages."
operations:
- method: GET
name: "list_folder_passages"
description: "List Folder Passages"
call: "letta-folders.list_folder_passages"
with:
"folder_id": "rest.folder_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/files"
name: "folders-by-id-files"
description: "REST surface for folders-by-id-files."
operations:
- method: GET
name: "list_files_for_folder"
description: "List Files for Folder"
call: "letta-folders.list_files_for_folder"
with:
"folder_id": "rest.folder_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
"include_content": "rest.include_content"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/files/{file-id}"
name: "folders-by-id-files-by-id"
description: "REST surface for folders-by-id-files-by-id."
operations:
- method: GET
name: "retrieve_file"
description: "Retrieve File"
call: "letta-folders.retrieve_file"
with:
"folder_id": "rest.folder_id"
"file_id": "rest.file_id"
"include_content": "rest.include_content"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/folders/{folder-id}/{file-id}"
name: "folders-by-id-by-id"
description: "REST surface for folders-by-id-by-id."
operations:
- method: DELETE
name: "delete_file_from_folder"
description: "Delete File from Folder"
call: "letta-folders.delete_file_from_folder"
with:
"folder_id": "rest.folder_id"
"file_id": "rest.file_id"
outputParameters:
- type: object
mapping: "$."
- type: mcp
namespace: "letta-folders-mcp"
port: 9090
transport: http
description: "MCP adapter for Letta API — Folders. One verb-noun tool per consumed operation."
tools:
- name: "count-folders"
description: "Count Folders"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.count_folders"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-folder"
description: "Retrieve Folder"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.retrieve_folder"
with:
"folder_id": "tools.folder_id"
outputParameters:
- type: object
mapping: "$."
- name: "modify-folder"
description: "Modify Folder"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-folders.modify_folder"
with:
"folder_id": "tools.folder_id"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "delete-folder"
description: "Delete Folder"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-folders.delete_folder"
with:
"folder_id": "tools.folder_id"
outputParameters:
- type: object
mapping: "$."
- name: "get-folder-name"
description: "Get Folder by Name"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.get_folder_by_name"
with:
"folder_name": "tools.folder_name"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-metadata"
description: "Retrieve Metadata"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.retrieve_metadata"
with:
"include_detailed_per_source_metadata": "tools.include_detailed_per_source_metadata"
outputParameters:
- type: object
mapping: "$."
- name: "list-folders"
description: "List Folders"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.list_folders"
with:
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
"name": "tools.name"
outputParameters:
- type: object
mapping: "$."
- name: "create-folder"
description: "Create Folder"
hints:
readOnly: false
destructive: false
idempotent: false
call: "letta-folders.create_folder"
with:
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "upload-file-folder"
description: "Upload File to Folder"
hints:
readOnly: false
destructive: false
idempotent: false
call: "letta-folders.upload_file_to_folder"
with:
"folder_id": "tools.folder_id"
"duplicate_handling": "tools.duplicate_handling"
"name": "tools.name"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "list-agents-folder"
description: "List Agents for Folder"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.list_agents_for_folder"
with:
"folder_id": "tools.folder_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "list-folder-passages"
description: "List Folder Passages"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.list_folder_passages"
with:
"folder_id": "tools.folder_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "list-files-folder"
description: "List Files for Folder"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.list_files_for_folder"
with:
"folder_id": "tools.folder_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
"include_content": "tools.include_content"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-file"
description: "Retrieve File"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-folders.retrieve_file"
with:
"folder_id": "tools.folder_id"
"file_id": "tools.file_id"
"include_content": "tools.include_content"
outputParameters:
- type: object
mapping: "$."
- name: "delete-file-folder"
description: "Delete File from Folder"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-folders.delete_file_from_folder"
with:
"folder_id": "tools.folder_id"
"file_id": "tools.file_id"
outputParameters:
- type: object
mapping: "$."