API Reference

Operations

Methods for rerun/manual generation and playbook aggregation.

Rerun and Manual Generation Operations

Profile and playbook generation can be triggered in different modes:

Mode	Method	Interactions	Output Status	Blocking	Use Case
Rerun	`rerun_*_generation`	ALL interactions	PENDING	Optional	Test prompt changes, full regeneration
Manual	`manual_*_generation`	Window-sized (from config)	CURRENT	Fire-and-forget only	Force regeneration, fill gaps

Key differences:

Rerun: Uses ALL interactions, outputs PENDING status (requires upgrade workflow), supports wait_for_response
Manual: Uses window_size from config, outputs CURRENT status directly, always fire-and-forget

The request source contract

Every source parameter uses the request source contract: it is a non-sensitive producer/workflow machine label, and empty means source absent where the API permits it. Every non-empty value must match ^[a-z0-9][a-z0-9._:-]{0,127}$ and is limited to 128 ASCII characters. Do not include user identifiers, email addresses, or other PII. For example, support-agent:v2 is valid.

rerun_profile_generationmethod

Regenerate user profiles from ALL existing interactions. Creates profiles with PENDING status.

response = client.rerun_profile_generation(    user_id="user_123",    wait_for_response=True)

Prop	Type
`user_id`	string
`start_time`	datetime
`end_time`	datetime
`source`	string
`extractor_names`	list[string]
`wait_for_response`	boolean

Returns RerunProfileGenerationResponse.

manual_profile_generationmethod

Manually trigger profile generation with window-sized interactions (fire-and-forget). Creates profiles with CURRENT status directly (no upgrade needed).

client.manual_profile_generation(user_id="user_123")

Prop	Type
`user_id`	string
`source`	string
`extractor_names`	list[string]

Returns: None (fire-and-forget operation)

Prerequisites:

window_size must be configured in your config
Extractors must have allow_manual_trigger=True to be included

Example

manual-profile-generation.py

# Force regeneration for a user (CURRENT status, fire-and-forget)client.manual_profile_generation(user_id="user_123") # Regenerate for all users with specific sourceclient.manual_profile_generation(source="support-agent:v2") # Legacy clients may still send extractor_names, but they no longer select extractors.client.manual_profile_generation(user_id="user_123")

rerun_playbook_generationmethod

Regenerate playbook entries from ALL interactions for a specific agent version. Creates entries with PENDING status.

response = client.rerun_playbook_generation(    agent_version="v2.1.0",    wait_for_response=True)

Prop	Type
`agent_version`required	string
`start_time`	datetime
`end_time`	datetime
`playbook_name`	string
`source`	string
`wait_for_response`	boolean

Returns RerunPlaybookGenerationResponse.

manual_playbook_generationmethod

Manually trigger playbook generation with window-sized interactions (fire-and-forget). Creates entries with CURRENT status directly (no upgrade needed).

client.manual_playbook_generation(agent_version="v2.1.0")

Prop	Type
`agent_version`required	string
`source`	string
`playbook_name`	string

Returns: None (fire-and-forget operation)

Prerequisites:

window_size must be configured in your config
Playbook configs must have allow_manual_trigger=True to be included

Example

manual-playbook-generation.py

# Force regeneration for an agent version (CURRENT status, fire-and-forget)client.manual_playbook_generation(agent_version="v2.1.0") # Regenerate with specific source filterclient.manual_playbook_generation(    agent_version="v2.1.0",    source="support-agent:v2") # Manual playbook generation runs the configured playbook extractor for the agent version.client.manual_playbook_generation(agent_version="v2.1.0")

upgrade_profilesmethod

Promote PENDING profiles to CURRENT, archive old CURRENT profiles, and delete old ARCHIVED profiles. Used after rerun_profile_generation to apply the new generation results.

response = client.upgrade_profiles(user_id="user_123")

Prop	Type
`user_id`	string
`only_affected_users`	boolean

Returns UpgradeProfilesResponse.

upgrade_user_playbooksmethod

Promote PENDING user playbooks to CURRENT, archive old CURRENT, and delete old ARCHIVED. Used after rerun_playbook_generation to apply the new generation results.

response = client.upgrade_user_playbooks(agent_version="v2.1.0")

Prop	Type
`agent_version`	string
`playbook_name`	string

Returns UpgradeUserPlaybooksResponse.

run_playbook_aggregationmethod

Aggregate user playbooks into consolidated insights using clustering.

response = client.run_playbook_aggregation(    agent_version="v2.1.0")

Prop	Type
`agent_version`required	string
`playbook_name`	string
`wait_for_response`	boolean

Returns RunPlaybookAggregationResponse.

clear_user_datamethod

Delete all rows scoped to a single user_id — the user's interactions, user playbooks, profiles, and requests. Does not touch agent playbooks, which are intentionally shared cross-project. Useful for isolating per-task data on a shared backend (e.g. paired-protocol harnesses) without a full clear-all.

response = client.clear_user_data(user_id="user_123")print(response.deleted_counts)

Prop	Type
`user_id`required	string

Returns ClearUserDataResponse.

Learning-Stall State

When a configured LLM provider returns an auth or billing error, Emend records a "learning stall" and pauses background extraction. These two methods let a client read and acknowledge that state.

get_stall_statemethod

Read the current learning-stall state from the server.

state = client.get_stall_state()if state.stalled:    print(state.reason, state.error_message)

Returns StallStateResponse.

mark_stall_notifiedmethod

Idempotently mark the current stall as notified (sets notified_in_cc=True).

result = client.mark_stall_notified()

Returns: MarkNotifiedResponse with the new notified_in_cc value.

PreviousRetrieval Experiments Next Human Questions