Get Citation Details Using CustomGPT RAG API – A Step-by-Step Guide

In this guide, you’ll learn how to retrieve citation details from a conversation message using the CustomGPT RAG API. We’ll walk through setting up an agent with a sitemap, starting a conversation, sending a message, and finally extracting citation information from the RAG API response. The explanations are written in a friendly, simple tone to help you understand every step.

1. Prerequisites to use CustomGPT RAG API

Before you begin, make sure you have the following:

• CustomGPT.ai Account: Sign up and log in at CustomGPT.ai.
• RAG API Key: Retrieve your RAG API token from your dashboard.
• Basic Python Knowledge: Knowing a bit about Python, REST APIs, and JSON will be helpful.
• Google Colab: We’re demonstrating this in Google Colab, but you can use any Python environment.
• Required Libraries: This notebook uses requests, json, and sseclient-py (for streaming responses) along with Google Colab’s file upload utilities.

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

With these basics covered, let’s set up your environment.

2. Setting Up Your Environment

Open the Notebook

Upload the Notebook: Open Google Colab and upload the Get_citation_details.ipynb file.

Install Dependencies

Make sure you have the necessary packages. For example, run:

!pip install sseclient-py

!pip install sseclient-py

Configure Your RAG API Key

At the beginning of the notebook, replace ‘YOUR_API_TOKEN‘ with your actual RAG API token:

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'YOUR_API_TOKEN'

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'YOUR_API_TOKEN'

Get Your RAG API Key

To get your RAG 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 your environment is ready, let’s dive into the code.

3. Code Walkthrough

This section explains the code step-by-step. We’ll cover how to create an agent from a sitemap, start a conversation, send a message, and finally extract citation details.

3.1 Creating an Agent with a Sitemap

In this step, we create a new agent by providing a name and a sitemap URL. This example uses a multipart/form-data request, which is useful for file uploads and form data.

# Setup API URL, API Token, and headers for file uploads

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'YOUR_API_TOKEN'

from google.colab import files

import requests

import json

# Agent details

project_name = 'Example ChatBot using Sitemap'

sitemap_path = 'https://adorosario.github.io/small-sitemap.xml'

# Construct payload for multipart/form-data

payload = {

    "project_name": (None, project_name),

    "sitemap_path": (None, sitemap_path)

}

headers = {

    'Authorization': 'Bearer ' + api_token

}

# Create the agent

url = api_endpoint + 'projects'

create_project = requests.request('POST', url, headers=headers, files=payload)

print(create_project.text)

# Setup API URL, API Token, and headers for file uploads

api_endpoint = 'https://app.customgpt.ai/api/v1/'

api_token = 'YOUR_API_TOKEN'

from google.colab import files

import requests

import json

# Agent details

project_name = 'Example ChatBot using Sitemap'

sitemap_path = 'https://adorosario.github.io/small-sitemap.xml'

# Construct payload for multipart/form-data

payload = {

    "project_name": (None, project_name),

    "sitemap_path": (None, sitemap_path)

}

headers = {

    'Authorization': 'Bearer ' + api_token

}

# Create the agent

url = api_endpoint + 'projects'

create_project = requests.request('POST', url, headers=headers, files=payload)

print(create_project.text)

Explanation:

• Payload Construction: The code builds a payload using the multipart/form-data format. It includes the agent’s name (project_name) and the sitemap URL (sitemap_path).
  
• Agent Creation: A POST request is sent to the /projects endpoint. Although the code uses “project” in the variable names, think of it as creating your agent. The response includes details like the unique agent ID.
  

Once your agent is created, we move on to creating a conversation within that agent.

3.2 Creating a Conversation Within the Agent

After creating the agent, we start a conversation. This helps set the stage for sending messages and later retrieving citation details.

# Extract agent ID from the agent creation response

data = json.loads(create_project.text)["data"]

project_id = data["id"]

# Prepare payload to create a conversation

name = 'Test Converasation'

payload = json.dumps({

    "name": project_name

})

headers = {

    'Content-type' : 'application/json',

    'Authorization': 'Bearer ' + api_token

}

# Create a conversation within the agent

url = api_endpoint + 'projects' + f"/{project_id}" + '/conversations'

create_conversation = requests.request('POST', url, headers=headers, data=payload)

print(create_conversation.text)

# Extract agent ID from the agent creation response

data = json.loads(create_project.text)["data"]

project_id = data["id"]

# Prepare payload to create a conversation

name = 'Test Converasation'

payload = json.dumps({

    "name": project_name

})

headers = {

    'Content-type' : 'application/json',

    'Authorization': 'Bearer ' + api_token

}

# Create a conversation within the agent

url = api_endpoint + 'projects' + f"/{project_id}" + '/conversations'

create_conversation = requests.request('POST', url, headers=headers, data=payload)

print(create_conversation.text)

Explanation:

• Extracting the Agent ID: The unique agent ID is extracted from the response of the agent creation call.
  
• Conversation Creation: A POST request is made to /projects/<project_id>/conversations to start a new conversation. The response contains a session_id, which is needed for the next steps.
  

With the conversation created, the next step is to send a message.

3.3 Sending a Message to the Conversation

Here, we send a message to the conversation. In this example, the response is returned in one complete chunk (non-streaming), which makes it easier to work with when extracting citation details.

# Install SSE Client (for streaming, if needed)

!pip install sseclient-py

from sseclient import SSEClient


# Extract conversation data and session_id

conversation_data = json.loads(create_conversation.text)["data"]

session_id = conversation_data["session_id"]


# Prepare and send the message to the conversation

prompt = "Who is Tom brady"

stream = 0  # 0 for non-streaming response


url = api_endpoint + 'projects/' + str(project_id) + '/conversations/' + str(session_id) + '/messages'


payload = json.dumps({

    "prompt": prompt,

    "stream": stream

})


response = requests.post(url, stream=False, headers=headers, data=payload)


print(response.text)

# Install SSE Client (for streaming, if needed)

!pip install sseclient-py

from sseclient import SSEClient


# Extract conversation data and session_id

conversation_data = json.loads(create_conversation.text)["data"]

session_id = conversation_data["session_id"]


# Prepare and send the message to the conversation

prompt = "Who is Tom brady"

stream = 0  # 0 for non-streaming response


url = api_endpoint + 'projects/' + str(project_id) + '/conversations/' + str(session_id) + '/messages'


payload = json.dumps({

    "prompt": prompt,

    "stream": stream

})


response = requests.post(url, stream=False, headers=headers, data=payload)


print(response.text)

Explanation:

• Message Preparation: The prompt “Who is Tom brady” is sent to the conversation endpoint. We set stream to 0 to get a single, complete response.
  
• Response Type: The non-streaming response is easier to parse because all the data is available in one go.
  

Now that we have the message response, we can extract the citation details.

3.4 Retrieving Citation Details

The message response contains an array of citation IDs. In this step, we extract the first citation ID and use it to fetch detailed citation information.

# Parse the message response to extract citation id

message_data = json.loads(response.text)['data']

citation_id = message_data['citations'][0]


# Construct the URL for retrieving citation details

url = api_endpoint + 'projects/' + str(project_id) + '/citations/' + str(citation_id)


citation_response = requests.get(url, headers=headers, data=payload)

print(citation_response.text)

# Parse the message response to extract citation id

message_data = json.loads(response.text)['data']

citation_id = message_data['citations'][0]


# Construct the URL for retrieving citation details

url = api_endpoint + 'projects/' + str(project_id) + '/citations/' + str(citation_id)


citation_response = requests.get(url, headers=headers, data=payload)

print(citation_response.text)

Explanation:

• Extracting Citation ID: The code parses the JSON response from the message to get the first citation ID from the citations field.
  
• Fetching Citation Details: A GET request is sent to /projects/<project_id>/citations/<citation_id> to retrieve detailed information about the citation. The detailed citation info is then printed out.
  

Now that we have walked through every step, let’s see how to run and verify the entire notebook.

4. Running and Testing the Notebook

Now that your notebook is set up, it’s time to execute it to create your project and upload files. Follow these instructions to make sure everything works as expected.

Step-by-Step Execution

1. Run Each Cell: Execute each cell in your notebook sequentially—from creating the agent to fetching citation details.
2. Monitor the Outputs:
   • Verify that the agent and conversation are created successfully.
   • Check that the message response contains citation IDs.
   • Confirm that the citation details are retrieved and printed correctly.

Verifying on CustomGPT.ai

Log in to your CustomGPT.ai dashboard to see your newly created agent. Review the citation details to ensure everything is processed as expected.

With everything running smoothly, let’s look at a few common issues you might face.

5. Troubleshooting Common Issues

Here are some common problems and simple fixes:

• Invalid RAG API Token: Double-check that you’ve replaced ‘YOUR_API_TOKEN‘ with your actual RAG API token and that it is active.
  
• Multipart/Form-Data Errors: Make sure the payload format is correct for file uploads and form data.
  
• JSON Parsing Errors: Confirm that the RAG API responses are valid JSON and that you’re using the correct keys to extract data.
  
• Missing Citation Data: If no citation data appears, verify that your conversation message is generating citations and check the RAG API documentation for any additional parameters you might need.
  

For more help, consult the official CustomGPT.ai documentation or join our community support.

6. Conclusion

Congratulations! In this guide, you learned how to use the CustomGPT.ai API and SDK to:

• Create an agent using a sitemap with the CustomGPT’s RAG API.
• Start a conversation within that agent.
• Send a message and extract citation details from the response.
• Retrieve detailed citation information using the citation ID.

This step-by-step process makes it easy to harness citation data from your chatbot interactions. Whether you need the citations for content validation or reference management, you now have the tools to get the job done.

If you have any questions or need further assistance, feel free to consult the CustomGPT.ai documentation or join our community. Happy coding, and enjoy building robust chatbot solutions with CustomGPT.ai!

Frequently Asked Questions

Related Resources

If you’re evaluating broader deployment options, this guide expands on how CustomGPT.ai supports production-grade RAG use cases.

• Enterprise RAG API — Explore how CustomGPT.ai’s enterprise RAG API supports scalable, secure retrieval-augmented generation for business applications.

Priyansh Khodiyar

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