Manage conversations and items¶

Create and maintain local conversation records containing metadata and item summaries. This task covers local conversations that are not associated with an upstream model. The application maintains message bodies and model-call context.

Prerequisites¶

Prepare a personal access token with Genesis permissions. For an existing conversation, use its identifier and the credential used to create it.

Call sequence¶

Create a conversation when a new record is needed and retain its identifier. For an existing conversation, use the saved identifier to retrieve it.
To change conversation metadata, read the current information, submit an update, and retrieve the conversation to confirm the replacement.
To record an item summary, add an item to the conversation and retain its returned identifier.
List items using the conversation identifier, or retrieve a single summary using both conversation and item identifiers.
When a summary or the entire conversation is no longer needed, optionally delete the corresponding object and check the deletion confirmation.

API operations¶

Manage conversation records¶

Task	API operation	When to use it or what to check
Create a conversation record	Create a conversation	Save metadata and optional item summaries, and obtain the conversation identifier.
Check a conversation	Retrieve a conversation	Read metadata, status, and timestamps using an existing identifier.
Replace conversation metadata	Update conversation metadata	Submit the complete replacement metadata when record information needs to change.
Remove a conversation	Delete a conversation	Use after confirming that API access to the conversation and its items is no longer needed.

Manage item summaries¶

Task	API operation	When to use it or what to check
Add an item summary	Create a conversation item	Record a summary such as type, role, and status in an existing conversation.
Browse item summaries	List conversation items	Check recorded items using the conversation identifier.
Check one summary	Retrieve a conversation item	Read a summary using its conversation and item identifiers.
Remove one summary	Delete a conversation item	Use after confirming the item is no longer needed.

Confirm the result¶

Retrieve the conversation after creation or an update to check its metadata. Retrieve an item after adding it to check its summary. Deleting a conversation makes it and its items inaccessible through the conversation API. Deleting an individual item makes that item inaccessible.

Limitations and notes¶

Local conversations do not store message bodies or automatically pass conversation content to a model.
Updating conversation metadata replaces all metadata. Retain information that must remain before submitting an update.
Local item lists return at most 200 items and do not support cursor pagination. The application must retain items and message bodies when a complete history is needed.

Last updated on Sep 15, 2026