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
Can I recover a deleted conversation?
No—deletion is permanent.
Does deleting free up credits?
Credits are spent at message time, not storage time, so deletion doesn’t refund usage.
Which fields are updatable on a conversation?
Only name and description.
Does renaming affect chat history?
No—messages remain intact under the new name.
How do I batch delete many sessions?
Loop through IDs from Conversation.list and call delete on each.
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-projects-using-pagination/
Need more detail? Dive into the CustomGPT API docs or open the GitHub Cookbook notebook for a runnable example.
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.
