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-'" 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-'" 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-'" - 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-'" - 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-'" 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-'" 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-'" - 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-'" - 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-'" - 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-'" - 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" hints: readOnly: false destructive: false idempotent: true call: "letta-identities.upsert_properties_for_identity" with: "identity_id": "tools.identity_id" "body": "tools.body" outputParameters: - type: object mapping: "$." - name: "upsert-properties-identity-2" description: "Upsert Properties for Identity" hints: readOnly: false destructive: false idempotent: true call: "letta-identities.upsert_properties_for_identity" with: "identity_id": "tools.identity_id" "body": "tools.body" outputParameters: - type: object mapping: "$." - name: "list-agents-identity" description: "List Agents for Identity" hints: readOnly: true destructive: false idempotent: true call: "letta-identities.list_agents_for_identity" with: "identity_id": "tools.identity_id" "before": "tools.before" "after": "tools.after" "limit": "tools.limit" "order": "tools.order" "order_by": "tools.order_by" "include": "tools.include" outputParameters: - type: object mapping: "$." - name: "list-blocks-identity" description: "List Blocks for Identity" hints: readOnly: true destructive: false idempotent: true call: "letta-identities.list_blocks_for_identity" with: "identity_id": "tools.identity_id" "before": "tools.before" "after": "tools.after" "limit": "tools.limit" "order": "tools.order" "order_by": "tools.order_by" outputParameters: - type: object mapping: "$."