Open-source Letta server (Apache-2.0) for self-hosted agent deployments. Same REST API surface as Letta Cloud, free to run; pay only for hosting and underlying LLM API usage. Default base URL is http://localhost:8283. Agents can be migrated between self-hosted and cloud via the open .af agent file format.
{
"openapi": "3.1.0",
"info": {
"title": "Letta API",
"version": "1.0.0",
"description": "REST API for Letta, the stateful agents platform. Manage agents, memory blocks, archival passages, sources, custom tools, MCP servers, multi-agent groups, runs, and streaming responses. Available as Letta Cloud (managed) at https://api.letta.com/v1 and as the self-hosted open-source server (Apache-2.0) typically run at http://localhost:8283.",
"contact": {
"name": "Letta",
"url": "https://www.letta.com/",
"email": "support@letta.com"
},
"license": {
"name": "Apache-2.0",
"url": "https://github.com/letta-ai/letta/blob/main/LICENSE"
},
"x-logo": {
"url": "https://www.letta.com/favicon.ico"
}
},
"servers": [
{
"url": "https://api.letta.com",
"description": "Letta Cloud (managed)"
},
{
"url": "https://app.letta.com",
"description": "Letta Cloud (app)"
},
{
"url": "http://localhost:8283",
"description": "Self-hosted Letta server"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v1/archives/": {
"post": {
"tags": [
"Archives"
],
"summary": "Create Archive",
"description": "Create a new archive.",
"operationId": "create_archive",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArchiveCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Archive"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Archives"
],
"summary": "List Archives",
"description": "Get a list of all archives for the current organization with optional filters and pagination.",
"operationId": "list_archives",
"parameters": [
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Archive ID cursor for pagination. Returns archives that come before this archive ID in the specified sort order",
"title": "Before"
},
"description": "Archive ID cursor for pagination. Returns archives that come before this archive ID in the specified sort order"
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Archive ID cursor for pagination. Returns archives that come after this archive ID in the specified sort order",
"title": "After"
},
"description": "Archive ID cursor for pagination. Returns archives that come after this archive ID in the specified sort order"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Maximum number of archives to return",
"default": 50,
"title": "Limit"
},
"description": "Maximum number of archives to return"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort order for archives by creation time. 'asc' for oldest first, 'desc' for newest first",
"default": "desc",
"title": "Order"
},
"description": "Sort order for archives by creation time. 'asc' for oldest first, 'desc' for newest first"
},
{
"name": "order_by",
"in": "query",
"required": false,
"schema": {
"const": "created_at",
"type": "string",
"description": "Field to sort by",
"default": "created_at",
"title": "Order By"
},
"description": "Field to sort by"
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by archive name (exact match)",
"title": "Name"
},
"description": "Filter by archive name (exact match)"
},
{
"name": "agent_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Only archives attached to this agent ID",
"title": "Agent Id"
},
"description": "Only archives attached to this agent ID"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Archive"
},
"title": "Response List Archives"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/archives/{archive_id}": {
"get": {
"tags": [
"Archives"
],
"summary": "Retrieve Archive",
"description": "Get a single archive by its ID.",
"operationId": "retrieve_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Archive"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Archives"
],
"summary": "Modify Archive",
"description": "Update an existing archive's name and/or description.",
"operationId": "modify_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArchiveUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Archive"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Archives"
],
"summary": "Delete Archive",
"description": "Delete an archive by its ID.",
"operationId": "delete_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/archives/{archive_id}/agents": {
"get": {
"tags": [
"Archives"
],
"summary": "List Agents for Archive",
"description": "Get a list of agents that have access to an archive with pagination support.",
"operationId": "list_agents_for_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
"title": "Before"
},
"description": "Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order"
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order",
"title": "After"
},
"description": "Agent ID cursor for pagination. Returns agents that come after this agent ID in the specified sort order"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Maximum number of agents to return",
"default": 50,
"title": "Limit"
},
"description": "Maximum number of agents to return"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first",
"default": "desc",
"title": "Order"
},
"description": "Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"enum": [
"agent.blocks",
"agent.identities",
"agent.managed_group",
"agent.pending_approval",
"agent.secrets",
"agent.sources",
"agent.tags",
"agent.tools"
],
"type": "string"
},
"description": "Specify which relational fields to include in the response. No relationships are included by default.",
"default": [],
"title": "Include"
},
"description": "Specify which relational fields to include in the response. No relationships are included by default."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentState"
},
"title": "Response List Agents For Archive"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/archives/{archive_id}/passages": {
"post": {
"tags": [
"Archives"
],
"summary": "Create Passage in Archive",
"description": "Create a new passage in an archive.\n\nThis adds a passage to the archive and creates embeddings for vector storage.",
"operationId": "create_passage_in_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PassageCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Passage"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/archives/{archive_id}/passages/batch": {
"post": {
"tags": [
"Archives"
],
"summary": "Create Passages in Archive",
"description": "Create multiple passages in an archive.\n\nThis adds passages to the archive and creates embeddings for vector storage.",
"operationId": "create_passages_in_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PassageBatchCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Passage"
},
"title": "Response Create Passages In Archive"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/archives/{archive_id}/passages/{passage_id}": {
"delete": {
"tags": [
"Archives"
],
"summary": "Delete Passage from Archive",
"description": "Delete a passage from an archive.\n\nThis permanently removes the passage from both the database and vector storage (if applicable).",
"operationId": "delete_passage_from_archive",
"parameters": [
{
"name": "archive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^archive-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the archive in the format 'archive-<uuid4>'",
"examples": [
"archive-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Archive Id"
},
"description": "The ID of the archive in the format 'archive-<uuid4>'"
},
{
"name": "passage_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 44,
"maxLength": 44,
"pattern": "^passage-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the passage in the format 'passage-<uuid4>'",
"examples": [
"passage-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Passage Id"
},
"description": "The ID of the passage in the format 'passage-<uuid4>'"
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tools/{tool_id}": {
"delete": {
"tags": [
"Tools"
],
"summary": "Delete Tool",
"description": "Delete a tool by name",
"operationId": "delete_tool",
"parameters": [
{
"name": "tool_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 41,
"maxLength": 41,
"pattern": "^tool-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the tool in the format 'tool-<uuid4>'",
"examples": [
"tool-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Tool Id"
},
"description": "The ID of the tool in the format 'tool-<uuid4>'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Tools"
],
"summary": "Retrieve Tool",
"description": "Get a tool by ID",
"operationId": "retrieve_tool",
"parameters": [
{
"name": "tool_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 41,
"maxLength": 41,
"pattern": "^tool-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the tool in the format 'tool-<uuid4>'",
"examples": [
"tool-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Tool Id"
},
"description": "The ID of the tool in the format 'tool-<uuid4>'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tool"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Tools"
],
"summary": "Modify Tool",
"description": "Update an existing tool",
"operationId": "modify_tool",
"parameters": [
{
"name": "tool_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 41,
"maxLength": 41,
"pattern": "^tool-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the tool in the format 'tool-<uuid4>'",
"examples": [
"tool-123e4567-e89b-42d3-8456-426614174000"
],
"title": "Tool Id"
},
"description": "The ID of the tool in the format 'tool-<uuid4>'"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tool"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/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.",
"operationId": "count_tools",
"parameters": [
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
{
"name": "names",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter by specific tool names",
"title": "Names"
},
"description": "Filter by specific tool names"
},
{
"name": "tool_ids",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter by specific tool IDs - accepts repeated params or comma-separated values",
"title": "Tool Ids"
},
"description": "Filter by specific tool IDs - accepts repeated params or comma-separated values"
},
{
"name": "search",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Search tool names (case-insensitive partial match)",
"title": "Search"
},
"description": "Search tool names (case-insensitive partial match)"
},
{
"name": "tool_types",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter by tool type(s) - accepts repeated params or comma-separated values",
"title": "Tool Types"
},
"description": "Filter by tool type(s) - accepts repeated params or comma-separated values"
},
{
"name": "exclude_tool_types",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Tool type(s) to exclude - accepts repeated params or comma-separated values",
"title": "Exclude Tool Types"
},
"description": "Tool type(s) to exclude - accepts repeated params or comma-separated values"
},
{
"name": "return_only_letta_tools",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Count only tools with tool_type starting with 'letta_'",
"default": false,
"title": "Return Only Letta Tools"
},
"description": "Count only tools with tool_type starting with 'letta_'"
},
{
"name": "exclude_letta_tools",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Exclude built-in Letta tools from the count",
"default": false,
"title": "Exclude Letta Tools"
},
"description": "Exclude built-in Letta tools from the count"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "integer",
# --- truncated at 32 KB (1714 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/openapi/letta-openapi.json