Chat projects accumulate test sessions, support threads, or demo conversations that you may want to rename for clarity—or remove entirely. This tutorial walks you through how to update and delete a conversation in code, using the CustomGPTs RAG APIs Python SDK implementation.
We’ll cover:
- Installing and authenticating the SDK
- Listing conversations to find the right session_id
- Renaming a conversation (updating its metadata)
- Deleting a conversation permanently
- Verifying the operations and handling errors
If you’re new to CustomGPT, first sign up and read Getting Started with CustomGPT.ai. For deeper reference, see the API docs and the companion notebook in the GitHub Cookbook.
Prerequisites
- API key with conversation‑management permissions
- Python 3 environment (Colab, Jupyter, or local)
- customgpt‑client installed:
pip install customgpt-client- The project ID that owns the conversation(s) you want to modify
- If you already know the session ID, great—otherwise we’ll fetch it
1 – Setup & Authentication
First, import the SDK and set your API key so future calls are authenticated automatically.
from customgpt_client import CustomGPT # Main SDK interface
CustomGPT.api_key = "YOUR_API_TOKEN" # ← Replace with your real tokenGet API keys
To get your API key, there are two ways:
Method 1 – Via Agent
- Agent > All Agents.
- Select your agent and go to deploy, click on the API key section and create an API.
Method 2 – Via Profile section.
- Go to profile (top right corner of your screen)
- Click on My Profile
- You will see the screen something like this (below screenshot). Here you can click on “Create API key”, give it a name and copy the key.
Please save this secret key somewhere safe and accessible. For security reasons, You won’t be able to view it again through your CustomGPT.ai account. If you lose this secret key, you’ll need to generate a new one.
Once the token is assigned, every SDK call will include the proper bearer header—no manual work needed.
2 – List Conversations to Identify a Session
If you don’t yet know which session_id to rename or delete, list recent conversations for your project.
conv_list = CustomGPT.Conversation.list(
project_id="YOUR_PROJECT_ID" # ← Replace with your project ID
)
# Display ID and current name for each conversation
for conv in conv_list.parsed.data.data:
print(f"ID: {conv.id} | Name: {conv.name}")What’s happening here?
Conversation.list calls GET /projects/{id}/conversations.
We access parsed.data.data, which holds a list of conversation objects, then print their IDs and names so you can pick the correct session.
Now that you have a session_id, let’s rename the conversation.
3 – Update (Rename) a Conversation
Renaming gives context—think “Q2 2025 Demo” or “Customer XYZ Onboarding.”
update_resp = CustomGPT.Conversation.update(
project_id="YOUR_PROJECT_ID", # ← Your project ID
session_id="YOUR_SESSION_ID", # ← Session you want to rename
name="June 2025 Support Session", # ← New name
description="Support chat covering June issues" # Optional description
)
print("Rename Status:", update_resp.status) # Should print "success"Line‑by‑line explanation
- Conversation.update sends a PATCH/PUT to /projects/{id}/conversations/{session_id}.
- The name field updates the visible label; description adds extra context.
- A “success” status means the server saved your changes.
Name updated—let’s see how to update and delete a conversation when you’re done with it.
4 – Delete a Conversation
Use deletion when a conversation is no longer relevant—or if policy requires purging old data.
delete_resp = CustomGPT.Conversation.delete(
project_id="YOUR_PROJECT_ID", # ← Same project ID
session_id="YOUR_SESSION_ID" # ← Session to remove
)
print("Delete Status:", delete_resp.status) # Expect "success"Heads‑up
This is irreversible. All messages inside that session are permanently removed.
To be extra sure, we’ll try to fetch the conversation and handle the expected error.
5 – Verify Deletion (Optional Safety Check)
Attempting to fetch a deleted conversation should error out—catch it to confirm.
try:
CustomGPT.Conversation.get(
project_id="YOUR_PROJECT_ID",
session_id="YOUR_SESSION_ID"
)
except Exception as e:
print("Expected error (session deleted):", e)If the SDK throws an exception (e.g., “Conversation not found”), you know the delete call succeeded.
Troubleshooting Tips
- Invalid token errors – Re‑check CustomGPT.api_key; regenerate if expired.
- Permission denied – Ensure your API key includes conversation‑management scopes.
- List returns empty – Verify the correct project_id and that conversations actually exist.
- Delete says “success” but still lists – Wait a few seconds and refresh; caching or pagination can briefly show stale data.
FAQs
Related Reading
- Retrieve Messages of a Conversation: https://customgpt.ai/sdk-retrieve-messages-of-conversation/
- List All Projects Using Pagination: https://customgpt.ai/sdk-list-all-agents-using-pagination/
Need more detail? Dive into the CustomGPT API docs or open the GitHub Cookbook notebook for a runnable example.
Frequently Asked Questions
Why can’t I find a trash icon or delete button for a conversation?
Conversation management in this workflow is done through the API/SDK rather than a UI delete control. You can list conversations to find the correct session_id, then delete that conversation using the project_id that owns it.
What permissions are required to rename or delete a conversation via the Python SDK?
You need an API key with conversation-management permissions. You also need the project ID for the project that owns the conversation you want to modify.
How do teams safely clean up old test conversations without deleting active support threads?
Start by listing conversations and identifying the exact session_id values you want to target. Rename conversations for clarity first, then delete only the selected sessions, and verify the results after each operation.
Can a deleted conversation be recovered later?
The guide describes deletion as permanent. Double-check the session_id and project_id before deleting to avoid removing the wrong conversation.
Why did my conversation rename call succeed but the old name still appears?
Rename in this workflow means updating conversation metadata. Re-list conversations after the update and confirm you changed the intended session_id under the correct project_id.
How can I delete conversation history for one user while keeping everyone else’s data?
Use conversation-level deletion: identify that user’s specific session_id values, then delete only those sessions in the relevant project. The key is accurate session identification before deletion.
Should I manage conversation cleanup with the SDK or direct REST calls?
If you’re working in Python, the documented approach is the CustomGPT Python SDK. For HTTP-level implementation details, use the API docs, and for runnable examples, use the companion notebook in the GitHub Cookbook.
Conclusion
You’ve just learned to:
- Authenticate the CustomGPT Python SDK
- List conversations to grab a session_id
- Rename a session to keep things organized
- Permanently delete a conversation when it’s no longer needed
- Verify your actions and handle errors gracefully
Use these techniques to keep your CustomGPT workspace tidy and compliant with your data‑retention policies. Happy coding—and may your chat history stay clean and manageable!
Make Money With AI
Join our Partner Programs!
Boost your reputation, drive revenue and grow your business with CustomGPT.ai.
Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.