Need to feed PDFs, Word docs, or plain‑text files into your chatbot’s knowledge base? This tutorial shows you exactly how to add a file to an agent (project), using the CustomGPTs RAG APIs Python SDK implementation. We’ll walk through:
- Installing and authenticating the SDK
- Reading a local file as bytes
- Uploading that file to an existing project (agent)
- Verifying that the file was indexed and is ready for chat
If you’re new to the platform, first check out Getting Started with CustomGPT.ai for New Developers, then come back here.
Notebook version: See the complete runnable code in our GitHub Cookbook.
Prerequisites
| Requirement | Details |
| CustomGPT Account & API Key | Create or sign in at CustomGPT → generate a token under Settings → API Tokens |
| Python 3 Environment | Google Colab, Jupyter Notebook, or local Python 3 |
| customgpt‑client SDK | Install with pip install customgpt-client |
| Project ID | The agent you want to add files to |
| Local File | PDF, TXT, DOCX, or MD—max ≈ 10 MB (plan‑dependent) |
When these are in place, we can jump into code.
1. Install & Authenticate the SDK
First, install the SDK (if you haven’t already) and set your API key so every call is authenticated.
# 1 – Install the CustomGPT SDK from PyPI
!pip install customgpt-client
# 2 – Import the SDK and helper class
from customgpt_client import CustomGPT # Main interface
from customgpt_client.types import File # Helper to wrap uploads
# 3 – Authenticate all SDK calls
CustomGPT.api_key = "YOUR_API_TOKEN" # ← replace with real tokenWhat’s happening?
- pip install downloads the SDK.
- CustomGPT exposes high‑level methods—no raw REST calls needed.
- File is a convenience wrapper that packages raw bytes + filename.
- Setting api_key means every SDK request includes your bearer token.
Get 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.
With authentication done, let’s read a file into memory.
2. Read the Local File
We need the file’s bytes so we can send them over HTTP.
# Path to the document you want to ingest
file_path = "path/to/document.pdf"
# Open in binary (rb) mode and read the bytes
with open(file_path, "rb") as f:
file_bytes = f.read() # ← now we have raw bytes
print("Read", len(file_bytes), "bytes")Why binary mode?
- Text mode (“r”) might alter line endings or encodings.
- Binary (“rb”) preserves the exact byte sequence for files like PDF/DOCX.
Now that we have raw bytes, we can build the payload expected by the SDK.
3. Construct the File Payload
Wrap the bytes and filename in the SDK’s File helper.
# Create a File object: payload = bytes, file_name = original name
file_payload = File(
payload = file_bytes, # Actual file data
file_name = "document.pdf" # Used by the backend to infer type
)Why use File?
The SDK needs to know:
- The binary content (payload) to upload.
- The filename (file_name) so CustomGPT can store and index correctly.
Using File packages both into a single object.
Payload ready? Let’s upload it to your project.
4. Upload the File to Your Project
Call the SDK’s add_file endpoint and point it at your project ID.
add_resp = CustomGPT.Project.add_file(
project_id = "YOUR_PROJECT_ID", # ← replace with real project
file = file_payload # ← object from previous step
)
print("Add File Status:", add_resp.status) # Expect "success"Under the hood
- Sends POST /projects/{id}/files with multipart/form‑data.
- CustomGPT splits the file into chunks and adds each as a “page.”
- The response contains page IDs so you can track indexing.
Upload accepted? Great—let’s confirm that indexing completes.
5. Verify File Indexing
We’ll query all pages for the project and look for our filename.
# Fetch pages created for this project
pages_resp = CustomGPT.Page.list(project_id="YOUR_PROJECT_ID")
pages = pages_resp.parsed.data.data # List of Page objects
# Filter pages originating from our file
for page in pages:
if page.file_name == "document.pdf":
print(f"Page ID: {page.id} | Status: {page.status}")Status values
| Status | Meaning |
| queued | Page is waiting to be crawled/embedded |
| indexing | Embeddings are being generated |
| indexed | Ready for chat queries |
| failed | Something went wrong (check file type/size) |
If you see indexed, your document is live in the chatbot’s knowledge base.
All set! Let’s cover some common questions before you head off.
FAQs
Which file types are supported?
PDF, DOCX, TXT, MD, and other standard text formats.
Can I upload multiple files?
Upload one file per call; loop for batch ingestion.
Max file size?
~10 MB (varies by plan).
Do uploads consume credits?
Yes—token usage corresponds to the file’s size/content.
Delete a mistakenly added file?
List pages, then call Page.delete(project_id, page_id) for each page created from that file.
Related Posts
Need more? Dive into the CustomGPT API docs or check the GitHub Cookbook for complete notebooks.
Next Steps
- Search your new content: Start a conversation and test queries specific to the uploaded file.
- Automate batching: Wrap the upload code in a loop for dozens of files.
- Combine with sitemaps: Blend file and URL content for a richer knowledge base.
Happy coding—and enjoy powering your chatbot with rich, document‑based knowledge!
Priyansh is Developer Relations Advocate who loves technology, writer about them, creates deeply researched content about them.
