Letta · Capability
Letta API — Identities
Identities — map external user identities to agents and per-user memory contexts. 18 operations. Lead operation: List Identities. Self-contained Naftiko capability covering one Letta business surface.
Letta API — Identities is a Naftiko capability published by Letta, one of 36 capabilities the APIs.io network indexes for this provider. It bundles 18 operations across the GET, PUT, POST, PATCH, and DELETE methods rooted at /v1/identities.
The capability includes 8 read-only operations and 10 state-changing operations. Lead operation: List Identities. Can be deployed as a REST endpoint, MCP tool, or Agent Skill via Naftiko.
Tagged areas include Letta, Stateful Agents, and Identities.
What You Can Do
GET
List_identities
— List Identities
/v1/identities/
GET
List_identities
— List Identities
/v1/identities/
POST
Create_identity
— Create Identity
/v1/identities/
POST
Create_identity
— Create Identity
/v1/identities/
PUT
Upsert_identity
— Upsert Identity
/v1/identities/
PUT
Upsert_identity
— Upsert Identity
/v1/identities/
GET
Count_identities
— Count Identities
/v1/identities/count
GET
Count_identities
— Count Identities
/v1/identities/count
GET
Retrieve_identity
— Retrieve Identity
/v1/identities/{identity-id}
GET
Retrieve_identity
— Retrieve Identity
/v1/identities/{identity-id}
PATCH
Update_identity
— Modify Identity
/v1/identities/{identity-id}
PATCH
Update_identity
— Modify Identity
/v1/identities/{identity-id}
DELETE
Delete_identity
— Delete Identity
/v1/identities/{identity-id}
DELETE
Delete_identity
— Delete Identity
/v1/identities/{identity-id}
PUT
Upsert_properties_for_identity
— Upsert Properties for Identity
/v1/identities/{identity-id}/properties
PUT
Upsert_properties_for_identity
— Upsert Properties for Identity
/v1/identities/{identity-id}/properties
GET
List_agents_for_identity
— List Agents for Identity
/v1/identities/{identity-id}/agents
GET
List_blocks_for_identity
— List Blocks for Identity
/v1/identities/{identity-id}/blocks
MCP Tools
list-identities
List Identities
read-only
idempotent
list-identities-2
List Identities
read-only
idempotent
create-identity
Create Identity
create-identity-2
Create Identity
upsert-identity
Upsert Identity
idempotent
upsert-identity-2
Upsert Identity
idempotent
count-identities
Count Identities
read-only
idempotent
count-identities-2
Count Identities
read-only
idempotent
retrieve-identity
Retrieve Identity
read-only
idempotent
retrieve-identity-2
Retrieve Identity
read-only
idempotent
modify-identity
Modify Identity
idempotent
modify-identity-2
Modify Identity
idempotent
delete-identity
Delete Identity
idempotent
delete-identity-2
Delete Identity
idempotent
upsert-properties-identity
Upsert Properties for Identity
idempotent
upsert-properties-identity-2
Upsert Properties for Identity
idempotent
list-agents-identity
List Agents for Identity
read-only
idempotent
list-blocks-identity
List Blocks for Identity
read-only
idempotent
Capability Spec
naftiko: "1.0.0-alpha2"
info:
label: "Letta API — Identities"
description: >-
Identities — map external user identities to agents and per-user memory contexts. 18 operations. Lead operation: List Identities. Self-contained Naftiko capability covering one Letta business surface.
tags:
- Letta
- Stateful Agents
- Identities
created: "2026-05-08"
modified: "2026-05-22"
binds:
- namespace: env
keys:
LETTA_API_KEY: LETTA_API_KEY
capability:
consumes:
- type: http
namespace: "letta-identities"
baseUri: "https://api.letta.com"
description: "Letta API — Identities business capability. Self-contained, no shared references."
authentication:
type: bearer
token: "{{env.LETTA_API_KEY}}"
resources:
- name: "identities"
path: "/v1/identities/"
operations:
- name: "list_identities"
method: GET
description: "List Identities"
inputParameters:
- name: "name"
in: query
type: string
required: false
description: "name parameter"
- name: "project_id"
in: query
type: string
required: false
description: "[DEPRECATED: Use X-Project-Id header instead] Filter identities by project ID"
- name: "identifier_key"
in: query
type: string
required: false
description: "identifier_key parameter"
- name: "identity_type"
in: query
type: string
required: false
description: "identity_type parameter"
- name: "before"
in: query
type: string
required: false
description: "Identity ID cursor for pagination. Returns identities that come before this identity ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Identity ID cursor for pagination. Returns identities that come after this identity ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of identities to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for identities 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: "list_identities_2"
method: GET
description: "List Identities"
inputParameters:
- name: "name"
in: query
type: string
required: false
description: "name parameter"
- name: "project_id"
in: query
type: string
required: false
description: "[DEPRECATED: Use X-Project-Id header instead] Filter identities by project ID"
- name: "identifier_key"
in: query
type: string
required: false
description: "identifier_key parameter"
- name: "identity_type"
in: query
type: string
required: false
description: "identity_type parameter"
- name: "before"
in: query
type: string
required: false
description: "Identity ID cursor for pagination. Returns identities that come before this identity ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Identity ID cursor for pagination. Returns identities that come after this identity ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of identities to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for identities 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: "create_identity"
method: POST
description: "Create Identity"
inputParameters:
- name: "X-Project"
in: header
type: string
required: false
description: "The project slug to associate with the identity (cloud only)."
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "create_identity_2"
method: POST
description: "Create Identity"
inputParameters:
- name: "X-Project"
in: header
type: string
required: false
description: "The project slug to associate with the identity (cloud only)."
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "upsert_identity"
method: PUT
description: "Upsert Identity"
inputParameters:
- name: "X-Project"
in: header
type: string
required: false
description: "The project slug to associate with the identity (cloud only)."
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "upsert_identity_2"
method: PUT
description: "Upsert Identity"
inputParameters:
- name: "X-Project"
in: header
type: string
required: false
description: "The project slug to associate with the identity (cloud only)."
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "identities-count"
path: "/v1/identities/count"
operations:
- name: "count_identities"
method: GET
description: "Count Identities"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "count_identities_2"
method: GET
description: "Count Identities"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "identities-by-id"
path: "/v1/identities/{identity_id}"
operations:
- name: "retrieve_identity"
method: GET
description: "Retrieve Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "retrieve_identity_2"
method: GET
description: "Retrieve Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "update_identity"
method: PATCH
description: "Modify Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "update_identity_2"
method: PATCH
description: "Modify Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "delete_identity"
method: DELETE
description: "Delete Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "delete_identity_2"
method: DELETE
description: "Delete Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "identities-by-id-properties"
path: "/v1/identities/{identity_id}/properties"
operations:
- name: "upsert_properties_for_identity"
method: PUT
description: "Upsert Properties for Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "upsert_properties_for_identity_2"
method: PUT
description: "Upsert Properties for Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "identities-by-id-agents"
path: "/v1/identities/{identity_id}/agents"
operations:
- name: "list_agents_for_identity"
method: GET
description: "List Agents for Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<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"
- 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: "identities-by-id-blocks"
path: "/v1/identities/{identity_id}/blocks"
operations:
- name: "list_blocks_for_identity"
method: GET
description: "List Blocks for Identity"
inputParameters:
- name: "identity_id"
in: path
type: string
required: true
description: "The ID of the identity in the format 'identity-<uuid4>'"
- name: "before"
in: query
type: string
required: false
description: "Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Block ID cursor for pagination. Returns blocks that come after this block ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of blocks to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for blocks 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: "$."
exposes:
- type: rest
namespace: "letta-identities-rest"
port: 8080
description: "REST adapter for Letta API — Identities. One Spectral-compliant resource per consumed operation."
resources:
- path: "/v1/identities/"
name: "identities"
description: "REST surface for identities."
operations:
- method: GET
name: "list_identities"
description: "List Identities"
call: "letta-identities.list_identities"
with:
"name": "rest.name"
"project_id": "rest.project_id"
"identifier_key": "rest.identifier_key"
"identity_type": "rest.identity_type"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- method: GET
name: "list_identities"
description: "List Identities"
call: "letta-identities.list_identities"
with:
"name": "rest.name"
"project_id": "rest.project_id"
"identifier_key": "rest.identifier_key"
"identity_type": "rest.identity_type"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- method: POST
name: "create_identity"
description: "Create Identity"
call: "letta-identities.create_identity"
with:
"X-Project": "rest.X-Project"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: POST
name: "create_identity"
description: "Create Identity"
call: "letta-identities.create_identity"
with:
"X-Project": "rest.X-Project"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: PUT
name: "upsert_identity"
description: "Upsert Identity"
call: "letta-identities.upsert_identity"
with:
"X-Project": "rest.X-Project"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: PUT
name: "upsert_identity"
description: "Upsert Identity"
call: "letta-identities.upsert_identity"
with:
"X-Project": "rest.X-Project"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/identities/count"
name: "identities-count"
description: "REST surface for identities-count."
operations:
- method: GET
name: "count_identities"
description: "Count Identities"
call: "letta-identities.count_identities"
outputParameters:
- type: object
mapping: "$."
- method: GET
name: "count_identities"
description: "Count Identities"
call: "letta-identities.count_identities"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/identities/{identity-id}"
name: "identities-by-id"
description: "REST surface for identities-by-id."
operations:
- method: GET
name: "retrieve_identity"
description: "Retrieve Identity"
call: "letta-identities.retrieve_identity"
with:
"identity_id": "rest.identity_id"
outputParameters:
- type: object
mapping: "$."
- method: GET
name: "retrieve_identity"
description: "Retrieve Identity"
call: "letta-identities.retrieve_identity"
with:
"identity_id": "rest.identity_id"
outputParameters:
- type: object
mapping: "$."
- method: PATCH
name: "update_identity"
description: "Modify Identity"
call: "letta-identities.update_identity"
with:
"identity_id": "rest.identity_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: PATCH
name: "update_identity"
description: "Modify Identity"
call: "letta-identities.update_identity"
with:
"identity_id": "rest.identity_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: DELETE
name: "delete_identity"
description: "Delete Identity"
call: "letta-identities.delete_identity"
with:
"identity_id": "rest.identity_id"
outputParameters:
- type: object
mapping: "$."
- method: DELETE
name: "delete_identity"
description: "Delete Identity"
call: "letta-identities.delete_identity"
with:
"identity_id": "rest.identity_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/identities/{identity-id}/properties"
name: "identities-by-id-properties"
description: "REST surface for identities-by-id-properties."
operations:
- method: PUT
name: "upsert_properties_for_identity"
description: "Upsert Properties for Identity"
call: "letta-identities.upsert_properties_for_identity"
with:
"identity_id": "rest.identity_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- method: PUT
name: "upsert_properties_for_identity"
description: "Upsert Properties for Identity"
call: "letta-identities.upsert_properties_for_identity"
with:
"identity_id": "rest.identity_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/identities/{identity-id}/agents"
name: "identities-by-id-agents"
description: "REST surface for identities-by-id-agents."
operations:
- method: GET
name: "list_agents_for_identity"
description: "List Agents for Identity"
call: "letta-identities.list_agents_for_identity"
with:
"identity_id": "rest.identity_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
"include": "rest.include"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/identities/{identity-id}/blocks"
name: "identities-by-id-blocks"
description: "REST surface for identities-by-id-blocks."
operations:
- method: GET
name: "list_blocks_for_identity"
description: "List Blocks for Identity"
call: "letta-identities.list_blocks_for_identity"
with:
"identity_id": "rest.identity_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- type: mcp
namespace: "letta-identities-mcp"
port: 9090
transport: http
description: "MCP adapter for Letta API — Identities. One verb-noun tool per consumed operation."
tools:
- name: "list-identities"
description: "List Identities"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.list_identities"
with:
"name": "tools.name"
"project_id": "tools.project_id"
"identifier_key": "tools.identifier_key"
"identity_type": "tools.identity_type"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "list-identities-2"
description: "List Identities"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.list_identities"
with:
"name": "tools.name"
"project_id": "tools.project_id"
"identifier_key": "tools.identifier_key"
"identity_type": "tools.identity_type"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "create-identity"
description: "Create Identity"
hints:
readOnly: false
destructive: false
idempotent: false
call: "letta-identities.create_identity"
with:
"X-Project": "tools.X-Project"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "create-identity-2"
description: "Create Identity"
hints:
readOnly: false
destructive: false
idempotent: false
call: "letta-identities.create_identity"
with:
"X-Project": "tools.X-Project"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "upsert-identity"
description: "Upsert Identity"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-identities.upsert_identity"
with:
"X-Project": "tools.X-Project"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "upsert-identity-2"
description: "Upsert Identity"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-identities.upsert_identity"
with:
"X-Project": "tools.X-Project"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "count-identities"
description: "Count Identities"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.count_identities"
outputParameters:
- type: object
mapping: "$."
- name: "count-identities-2"
description: "Count Identities"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.count_identities"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-identity"
description: "Retrieve Identity"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.retrieve_identity"
with:
"identity_id": "tools.identity_id"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-identity-2"
description: "Retrieve Identity"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-identities.retrieve_identity"
with:
"identity_id": "tools.identity_id"
outputParameters:
- type: object
mapping: "$."
- name: "modify-identity"
description: "Modify Identity"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-identities.update_identity"
with:
"identity_id": "tools.identity_id"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "modify-identity-2"
description: "Modify Identity"
hints:
readOnly: false
destructive: false
idempotent: true
call: "letta-identities.update_identity"
with:
"identity_id": "tools.identity_id"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."
- name: "delete-identity"
description: "Delete Identity"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-identities.delete_identity"
with:
"identity_id": "tools.identity_id"
outputParameters:
- type: object
mapping: "$."
- name: "delete-identity-2"
description: "Delete Identity"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-identities.delete_identity"
with:
"identity_id": "tools.identity_id"
outputParameters:
- type: object
mapping: "$."
- name: "upsert-properties-identity"
description: "Upsert Properties for Identity"
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/letta/refs/heads/main/capabilities/letta-identities.yaml