Get Citation Details of an Agent with CustomGPT.ai RAG API’s Python SDK – A Detailed Developer Guide

Watch the demo video at the top for a step‑by‑step walkthrough! (coming soon)

1. Introduction

Welcome, developers! In this guide, we’ll dive deep into how to fetch citation details for a chatbot conversation using the CustomGPT Python SDK. Citations let you trace back exactly which source—be it a web page or an uploaded file—your chatbot used when answering a user’s question. We’ll cover:

1. Installing and configuring the SDK
   
2. Creating a project (agent)
   
3. Starting a conversation
   
4. Sending a message and receiving citations
   
5. Retrieving full citation details
   

Make sure you have read our Getting Started with CustomGPT.ai for New Developers blog to get an overview of the entire platform.

By the end, you’ll be able to programmatically inspect where your chatbot’s content comes from. For full API reference, see the CustomGPT API docs

Code – https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Get_Citation_Details.ipynb

2. Prerequisites

Before we start, please ensure you have:

• CustomGPT.ai Account & API Key:
  Sign in to CustomGPT.ai, navigate to Settings → API Tokens, and generate a token.
  
• Python 3 Environment:
  Use Google Colab, Jupyter Notebook, or any Python 3 setup.
  
• Basic Python & REST Knowledge:
  You should be comfortable installing packages, importing modules, and handling JSON-like objects.
  

Once you’ve got these ready, let’s install and initialize the SDK.

3. Setting Up the SDK

We’ll begin by installing the customgpt-client package and configuring it with your API token. This grants access to high‑level methods for projects, conversations, messages, and citations.

# Install the CustomGPT Python SDK from PyPI
!pip install customgpt-client

# Import the SDK’s main class
from customgpt_client import CustomGPT

# Set your API key so all subsequent calls are authenticated
CustomGPT.api_key = "YOUR_API_TOKEN"  # ← Replace with your actual token

• pip install customgpt-client fetches the SDK package.
  
• from customgpt_client import CustomGPT imports the class that wraps all API endpoints.
  
• CustomGPT.api_key = … ensures each SDK call includes your token in the header.
  

Get API keys

To get your API key, there are two ways:

Method 1 – Via Agent

1. Agent > All Agents.
2. Select your agent and go to deploy, click on the API key section and create an API. 

Method 2 – Via Profile section.

1. Go to profile (top right corner of your screen)
2. Click on My Profile
3. 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.

Now that the SDK is ready, let’s create a project (agent) to host our conversation.

4. Creating a Project (Agent)

Your agent is the container for your chatbot’s knowledge. We’ll point it at a sitemap so it can index content from multiple URLs.

# Define the name for your agent
project_name  = 'Example ChatBot using Sitemap'

# Provide a sitemap URL listing pages your chatbot should index
sitemap_path   = 'https://adorosario.github.io/small-sitemap.xml'

# Create the agent using the SDK
create_project = CustomGPT.Project.create(
    project_name=project_name,
    sitemap_path=sitemap_path
)

# Print the full creation response to inspect details
print("Create Project Response:", create_project)

1. project_name: A human‑readable label for your agent.
   
2. sitemap_path: A URL to your sitemap.xml, which the agent will crawl.
   
3. CustomGPT.Project.create: Sends a POST request under the hood to /projects.
   
4. Response: Contains fields like id, project_name, and is_chat_active.
   

Once the project exists, we can move on to starting a conversation.

5. Creating a Conversation

Conversations let you interact with your agent and accumulate messages (and citations). Let’s open a new conversation session.

# Parse out the project ID from the creation response
project_id = create_project.parsed.data.id

# Create a conversation within this project
create_conversation = CustomGPT.Conversation.create(
    project_id=project_id,
    name="Test Conversation"
)

# Print the response to see the conversation’s session ID
print("Create Conversation Response:", create_conversation)

• create_project.parsed.data.id retrieves the numeric project ID.
  
• CustomGPT.Conversation.create sends a POST to /projects/{id}/conversations.
  
• Response contains session_id—you’ll need this to send messages.
  

Now that we have a session, let’s send a question and see citations in action

6. Sending a Message and Receiving Citations

When you send a prompt, the agent responds and includes an array of citation IDs—references to the sources it used. Here’s how to send a message:

# Extract the session_id from the conversation response
session_id = create_conversation.parsed.data.session_id

# Define the user’s question
prompt = "Who is Tom Brady in 10 words?"

# Send the message; by default stream=False, so we get the full response at once
send_conversation = CustomGPT.Conversation.send(
    project_id=project_id,
    session_id=session_id,
    prompt=prompt,
    stream=False  # non-streaming call
)

# Print the message response, including citations IDs
print("Send Conversation Response:", send_conversation)

1. session_id: Uniquely identifies your chat session.
   
2. prompt: Your question to the bot.
   
3. CustomGPT.Conversation.send: Calls POST on /projects/{id}/conversations/{session_id}/messages.
   
4. Response: Contains openai_response (the bot’s answer) and citations (an array of citation IDs).
   

Next, we’ll pick one citation ID and fetch its full details.

7. Retrieving Full Citation Details

A citation ID points to a resource—either a URL or an uploaded file segment. Here’s how to fetch the metadata for one citation:

# Grab the first citation ID from the message response
citation_id = send_conversation.parsed.data.citations[0]
print("Citation ID to fetch:", citation_id)

# Retrieve full citation details via the SDK
citation = CustomGPT.Citation.get(
    project_id=project_id,
    citation_id=citation_id
)

# Print the citation object, which includes page_url or file_url
print("Citation Details:", citation)

• citations[0]: The first citation ID in the array.
  
• CustomGPT.Citation.get: Sends GET to /projects/{id}/citations/{citation_id}.
  
• Response: Gives you page_url, url, or file metadata so you can access the original source.
  

With these details, you can verify where your chatbot’s information comes from.

8. Troubleshooting Common Issues

• No Citations Returned:
  Ensure your project indexed content successfully and your prompt triggers citation-enabled responses.
  
• Invalid Token Errors:
  Confirm CustomGPT.api_key is correct and hasn’t expired.
  
• Permission Denied:
  Verify the API token has citation‐reading scopes.
  
• Network Errors:
  Check your internet connection and that app.customgpt.ai is reachable.

For more troubleshooting tips, see the CustomGPT API docs.

9. Conclusion

Congratulations! You’ve just learned how to:

1. Install and configure the CustomGPT Python SDK.
   
2. Create a project (agent) from a sitemap.
   
3. Open a conversation and send a message.
   
4. Retrieve citation IDs from the response.
   
5. Fetch detailed citation information to trace your chatbot’s sources.
   

By integrating citation retrieval into your workflow, you add transparency to your chatbot’s answers and can audit or display sources easily. For more details on the SDK and API, explore the official documentation.

Happy coding, and may your bots always cite their sources!

Priyansh Khodiyar

Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.