CustomGPT API Integration

Role: Developer API Assistant

I help developers write code that integrates with CustomGPT.ai APIs. I know all endpoints, authentication patterns, and best practices.

Capabilities

• Generate API integration code (Python, JavaScript, curl)
• Authentication setup (API keys, Bearer tokens)
• All endpoint patterns (agents, conversations, sources, analytics)
• Error handling and retry logic
• SDK usage patterns

When to Use

DO use for:

• Writing code to call CustomGPT APIs
• Setting up authentication
• Creating/managing agents programmatically
• Building conversation flows
• Fetching analytics data

DO NOT use for:

• Querying knowledge bases (use customgpt-rag)
• General REST API questions unrelated to CustomGPT

Authentication

Base URL: https://app.customgpt.ai

All requests require Bearer token:

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

Get your API key from: Settings > API Keys in the CustomGPT dashboard.

Endpoint Reference

Agents (Projects)

Conversations

Messages

Sources

Pages (Content)

Analytics

Settings

Citations

Labels

Licenses

Users

Code Patterns

Python: Create Agent

import requests

API_KEY = "your_api_key"
BASE_URL = "https://app.customgpt.ai"

response = requests.post(
    f"{BASE_URL}/api/v1/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "project_name": "My Knowledge Base",
        "sitemap_path": "https://example.com/sitemap.xml"
    }
)
agent = response.json()["data"]
print(f"Created agent: {agent['id']}")

Python: Send Message (Get RAG Response)

import requests

project_id = "your_project_id"
session_id = "your_session_id"  # From create conversation

response = requests.post(
    f"{BASE_URL}/api/v1/projects/{project_id}/conversations/{session_id}/messages",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"prompt": "What is your return policy?"}
)
data = response.json()["data"]
answer = data["openai_response"]
citations = data.get("citations", [])

Python: Create Conversation

response = requests.post(
    f"{BASE_URL}/api/v1/projects/{project_id}/conversations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "Support Chat"}
)
session_id = response.json()["data"]["session_id"]

Python: OpenAI-Compatible Format

response = requests.post(
    f"{BASE_URL}/api/v1/projects/{project_id}/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "messages": [{"role": "user", "content": "Hello, what can you help with?"}],
        "stream": False
    }
)
completion = response.json()

Python: Streaming Response

response = requests.post(
    f"{BASE_URL}/api/v1/projects/{project_id}/conversations/{session_id}/messages",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"prompt": "Explain our pricing", "stream": True},
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode())

JavaScript: List Agents

const API_KEY = "your_api_key";
const BASE_URL = "https://app.customgpt.ai";

const response = await fetch(`${BASE_URL}/api/v1/projects`, {
  headers: { "Authorization": `Bearer ${API_KEY}` }
});
const { data } = await response.json();
console.log(`Found ${data.length} agents`);

JavaScript: Send Message

const response = await fetch(
  `${BASE_URL}/api/v1/projects/${projectId}/conversations/${sessionId}/messages`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ prompt: "What topics do you cover?" })
  }
);
const { data } = await response.json();
console.log(data.openai_response);

curl: Quick Test

# List agents
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.customgpt.ai/api/v1/projects

# Send message
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}' \
  "https://app.customgpt.ai/api/v1/projects/{id}/conversations/{sid}/messages"

Error Handling

import time

def call_api(url, method="GET", data=None, max_retries=3):
    headers = {"Authorization": f"Bearer {API_KEY}"}

    for attempt in range(max_retries):
        if method == "GET":
            response = requests.get(url, headers=headers)
        else:
            response = requests.post(url, headers=headers, json=data)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 401:
            raise Exception("Invalid API key - check your credentials")
        elif response.status_code == 403:
            raise Exception("Access denied - check permissions")
        elif response.status_code == 404:
            raise Exception("Resource not found")
        elif response.status_code == 429:
            wait = 2 ** attempt * 10  # Exponential backoff
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
        elif response.status_code >= 500:
            time.sleep(5)  # Server error, brief wait
        else:
            raise Exception(f"API error: {response.status_code}")

    raise Exception("Max retries exceeded")

Response Format

All endpoints return:

{
  "status": "success",
  "data": { ... }
}

Error responses:

{
  "status": "error",
  "message": "Error description"
}

Rate Limits

• Respect 429 responses with exponential backoff
• Batch operations where possible
• Cache responses when appropriate

Related

• API Reference: https://docs.customgpt.ai/reference
• Getting Started: https://docs.customgpt.ai/docs/welcome
• MCP Integration: https://docs.customgpt.ai/mcp
• customgpt-rag skill: For querying knowledge bases via MCP