Client Methods

Profile Management

Methods for searching, retrieving, and deleting user profiles, plus profile changelog.

Deprecation Warning

search_profiles is a deprecated compatibility alias for search_user_profiles. New integrations should use search_user_profiles; the alias emits DeprecationWarning and will be removed in a future release.

`search_user_profiles`

Search for user profiles using semantic queries.

Python

response = client.search_user_profiles(
    user_id="user_123",
    query="laptop preferences",
    tags=["hardware"],
    threshold=0.7,
    top_k=5
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_profiles" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "query": "laptop preferences",
  "tags": ["hardware"],
  "threshold": 0.7,
  "top_k": 5
}
JSON

Prop	Type	Default	Description
`user_id`	`str`	`—`	Identifier of the user to search and identify for retrieval-experiment assignment. Required for agent traffic while an experiment is active.
`generated_from_request_id?`	`str`	`—`	Filter by request ID that generated the profile
`query?`	`str`	`—`	Semantic search query
`start_time?`	`datetime`	`—`	Filter by start time
`end_time?`	`datetime`	`—`	Filter by end time
`top_k?`	`int`	`10`	Maximum number of results to return
`source?`	`str`	`—`	Filter by interaction source
`custom_feature?`	`str`	`—`	Filter by custom features
`extractor_name?`	`str`	`—`	Deprecated compatibility filter for legacy stored profiles. New singleton extraction does not use names for selection.
`tags?`	`string[]`	`—`	Optional tag filter. Matches profiles that have any requested tag.
`threshold?`	`float`	`model-specific`	Similarity threshold (0.0-1.0). Omit it to use the embedding model's default.
`enable_reformulation?`	`bool`	`false`	Enable query reformulation for improved search results
`search_mode?`	SearchMode	`—`	Search mode: "vector", "fts", or "hybrid". When unset, the server uses its configured default ("hybrid").

`rerank_user_profiles`

Rerank a list of candidate profile IDs by query relevance using a cross-encoder. Use after search_user_profiles (or any other source of candidate IDs) when initial results are noisy. The server fetches each candidate's full content (scoped to user_id), scores (query, content) pairs, and returns the top_k profiles sorted by descending score. IDs that don't resolve for the user are silently dropped.

Python

response = client.rerank_user_profiles(
    user_id="user_123",
    query="laptop preferences",
    profile_ids=["prof_1", "prof_2", "prof_3"],
    top_k=5,
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/rerank_user_profiles" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "query": "laptop preferences",
  "profile_ids": [
    "prof_1",
    "prof_2",
    "prof_3"
  ],
  "top_k": 5
}
JSON

Prop	Type	Default	Description
`user_id`	`str`	`—`	The user whose profiles to rerank
`query`	`str`	`—`	The reranking query
`profile_ids`	`list[str]`	`—`	Candidate profile IDs to score
`top_k?`	`int`	`10`	Maximum profiles to return

Returns: SearchProfilesViewResponse with success, user_profiles (sorted by descending cross-encoder score, capped at top_k), and msg.

`storage_stats`

Get a lightweight count of how many profiles and playbooks a user has, plus the modified-time range across every status. Useful for sizing top_k before retrieval.

Python

stats = client.storage_stats(user_id="user_123")
print(stats.profile_count, stats.playbook_count)

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/storage_stats?user_id=user_123" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop	Type	Default	Description
`user_id`	`str`	`—`	The user to inspect

`get_profiles`

Retrieve user profiles.

Python

response = client.get_profiles(
    user_id="user_123",
    tags=["hardware"],
    top_k=10
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_profiles" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "user_123",
  "tags": ["hardware"],
  "top_k": 10
}
JSON

Prop	Type	Default	Description
`user_id`	`str`	`—`	Identifier of the user to query
`profile_id?`	`str`	`—`	Exact profile ID filter
`query?`	`str`	`—`	Case-insensitive text filter across visible profile fields
`start_time?`	`datetime`	`—`	Filter by start time
`end_time?`	`datetime`	`—`	Filter by end time
`top_k?`	`int`	`30`	Maximum number of results to return
`source?`	`str`	`—`	Filter by exact profile source
`profile_time_to_live?`	`str`	`—`	Filter by profile TTL value
`status_filter?`	list[Status \| str]	`—`	Filter by profile status. Accepts Status enum or string values (e.g., "current", "archived", "pending")
`tags?`	`string[]`	`—`	Optional tag filter. Matches profiles that have any requested tag.
`force_refresh?`	`bool`	`false`	Bypass cache

`get_all_profiles`

Get profiles across all users (admin operation).

Python

response = client.get_all_profiles(limit=100)

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_all_profiles?limit=100" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop	Type	Default	Description
`limit?`	`int`	`100`	Maximum profiles to return
`status_filter?`	`str`	`—`	Filter by profile status. Accepts "current", "pending", or "archived". If unset, profiles with any status are returned.
`user_id?`	`str`	`—`	Filter by exact user ID
`profile_id?`	`str`	`—`	Filter by exact profile ID
`query?`	`str`	`—`	Case-insensitive text filter across visible profile fields
`source?`	`str`	`—`	Filter by exact profile source
`profile_time_to_live?`	`str`	`—`	Filter by profile TTL value
`start_time?`	`int`	`—`	Inclusive minimum epoch seconds for date_field
`end_time?`	`int`	`—`	Inclusive maximum epoch seconds for date_field
`date_field?`	`Literal["last_modified_timestamp", "created_at"]`	`"last_modified_timestamp"`	Date column used for start_time and end_time; use created_at for creation-time cohorts. Filtering occurs before the result limit.

Returns: GetUserProfilesResponse with profiles from all users

Example:

Python

# Get profiles from all users
all_profiles = client.get_all_profiles(limit=50)

# Group by user
from collections import defaultdict
by_user = defaultdict(list)

for profile in all_profiles.user_profiles:
    by_user[profile.user_id].append(profile)

for user_id, profiles in by_user.items():
    print(f"User {user_id}: {len(profiles)} profiles")
    for p in profiles[:3]:  # Show first 3
        print(f"  - {p.content[:50]}...")

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_all_profiles?limit=50" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

`add_user_profile`

Add user profiles directly to storage, bypassing the inference pipeline. Useful for seeding known facts (testing, migration, manual injection). The server populates the embedding automatically.

Python

response = client.add_user_profile(
    user_profiles=[
        {"user_id": "user_123", "content": "Prefers concise responses"},
    ]
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/add_user_profile" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_profiles": [
    {
      "user_id": "user_123",
      "content": "Prefers concise responses"
    }
  ]
}
JSON

Prop	Type	Default	Description
`user_profiles`	list[UserProfile \| dict]	`—`	List of profiles. Each entry must include at least `user_id` and `content`. When passing dicts, an omitted `profile_id` is generated as a canonical UUIDv4 string; other missing required fields are auto-populated client-side with sensible defaults.

`delete_profile`

Delete user profiles by ID or search query.

Python

response = client.delete_profile(
    user_id,
    profile_id="",
    search_query="",
    wait_for_response=False
)

Terminal

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_profile" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "<user_id>",
  "profile_id": "",
  "search_query": ""
}
JSON

Prop	Type	Default	Description
`user_id`	`str`	`—`	User identifier
`profile_id?`	`str`	`""`	Specific profile ID to delete
`search_query?`	`str`	`""`	Delete profiles matching query
`wait_for_response?`	`bool`	`false`	Wait for confirmation

`get_profile_change_log`

Retrieve the history of profile changes.

Python

logs = client.get_profile_change_log()

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/profile_change_log" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Bulk Delete Operations

`delete_profiles_by_ids`

Delete multiple profiles by their IDs.

Python

response = client.delete_profiles_by_ids(profile_ids=["prof_1", "prof_2"])

Terminal

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_profiles_by_ids" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "profile_ids": [
    "prof_1",
    "prof_2"
  ]
}
JSON

Prop	Type	Default	Description
`profile_ids`	`list[str]`	`—`	List of profile IDs to delete

Returns: BulkDeleteResponse with success, deleted_count, and message

`delete_all_profiles`

Delete all profiles.

Python

response = client.delete_all_profiles()

Terminal

curl -X DELETE "${REFLEXIO_URL:-https://www.reflexio.ai}/api/delete_all_profiles" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Returns: BulkDeleteResponse with success, deleted_count, and message

SearchUserProfileResponse Schema

UserProfile Schema

StorageStatsResponse Schema

GetUserProfilesResponse Schema

AddUserProfileResponse Schema

DeleteUserProfileResponse Schema

ProfileChangeLogResponse Schema

ProfileChangeLog Schema

Client Methods

Interaction Models

Configuration Guide

Searching Learned Context