--- updatedAt: 2025-11-12T19:07:45.000Z agentTools: projectIndex: https://docs.customgpt.ai/llms.txt --- # CustomGPT.ai API Getting started with CustomGPT's API is quick and easy. This quickstart guide aims to facilitate the process of getting you prepared for your first [API](https://customgpt.ai/api/) call. If you are looking for our application, visit ## Create API key As a whole, getting started with the [CustomGPT API](https://customgpt.ai/api/) goes as follows: 1. Create an [Account](https://docs.customgpt.ai/docs/create-your-customgpt-account) or Log In 2. Acquire your [API Key](https://docs.customgpt.ai/reference/api-keys-and-authentication) 3. Create an [Agent](https://docs.customgpt.ai/reference/post_api-v1-projects) 4. Create a [Conversation](https://docs.customgpt.ai/reference/post_api-v1-projects-projectid-conversations) 5. [Send a Message](https://docs.customgpt.ai/reference/post_api-v1-projects-projectid-conversations-sessionid-messages) to the Conversation This guide will walk you through the above workflow in a bit more detail. Feel free to look around our documentation hub for more information on any part listed. ## Step 1: Create an Account or Log In To use the CustomGPT website and API, you'll need to sign up for an account. Sign up or log in [here](https://app.customgpt.ai/login). For more information, see our [guide](https://docs.customgpt.ai/docs/create-your-customgpt-account) on creating an account and logging in.
## Step 2: Acquiring the API key 1. From [the app](https://app.customgpt.ai/), click on the circle in the top right corner of the dashboard and select the [**"My Profile"**](https://app.customgpt.ai/profile) option from the dropdown menu that appears. 2. Select the [**API**](https://app.customgpt.ai/profile#api) tab and press the **Create API Key** button to generate a new API key.
## Step 3: Create an Agent **API Terminology: Agents vs. Projects** In the CustomGPT.ai API, **agents** are referred to as **projects** in endpoint URLs, request/response structures, and parameters. While our platform has fully transitioned to using the term **agents** across the UI and documentation, the API retains the legacy terminology for backward compatibility. When interacting with the API, any reference to **"projects"** in endpoints, request bodies, query parameters, or responses corresponds to **"agents"** in the current system. *** Authentication to the API is performed via HTTP Basic Auth. To authenticate with CustomGPT API endpoints, you must provide the API Key in the header, as shown below. ```curl Authentication Header 'authorization: Bearer Your_API_KEY' ``` For example, you will use the `POST - Create new agent` endpoint to create a new project. In this scenario, you can send an API request by adding your API Key in the Authentication header and the sitemap you wish to use as a data source in the sitemap\_path as shown below: ```curl curl --request POST \ --url 'https://app.customgpt.ai/api/v1/projects' \ --header 'accept: application/json' \ --header 'authorization: Bearer Your_API_KEY' \ --header 'content-type: application/json' \ --data ' { "project_name": "Test", "sitemap_path": "https://example.com/sitemap.xml" } ' ``` > If you require assistance, or have additional feedback on the API or its documentation, reach out to *** ## Step 4: Create a Conversation A conversation object represents a forum for communication between a user and the Agent. Conversations can be created every time a new message is sent, or messages can be sent to an existing conversation via the sessionID. ```curl curl --request POST \ --url https://app.customgpt.ai/api/v1/projects/projectID/conversations \ --header 'accept: application/json' \ --header 'authorization: Bearer Your_API_KEY' \ --header 'content-type: application/json' \ --data ' { "name": "New Conversation Name" } ' ``` *** ## Step 5: Send a Message Now that a conversation has been created, you can send a message to that conversation. The response you will receive is the response from your AI Agent. To send a message to the conversation, you will need the sessionID and the projectID. ```curl curl --request POST \ --url https://app.customgpt.ai/api/v1/projects/ProjectID/conversations/SessionID/messages \ --header 'accept: application/json' \ --header 'authorization: Bearer API-KEY' \ --header 'content-type: application/json' \ --data ' { "response_source": "default", "prompt": "Hello world" } ' ```
# CustomGPT.ai API & Developer Features Overview ## **API Overview** CustomGPT.ai offers a [**#1-ranked RAG (Retrieval-Augmented Generation) API**](https://customgpt.ai/press-release-anti-hallucination-benchmark/) that transforms business data into intelligent AI agents. The serverless platform provides enterprise-grade security (SOC 2 Type 2), handles billions of words, and delivers 34% faster response times than competitors with 13% higher accuracy and 10% lower hallucination rates. Make sure you have read our Getting Started with [CustomGPT.ai for New Developers](https://customgpt.ai/getting-started-with-customgpt-for-new-developers/) blog to get an overview of the entire platform. ### Key Capabilities: * [RESTful API](https://customgpt.ai/api/) with comprehensive endpoints * [Python SDK](https://docs.customgpt.ai/reference/learn-more#/) with sync/async support * **Select from[models](https://docs.customgpt.ai/docs/how-to-choose-the-right-gpt-model-for-your-ai-agent#/)** - GTP-5, GPT-4o, GPT-4o mini, GPT-4.1, GPT-4.1 mini, Claude, etc * [Hosted MCP Support](https://docs.customgpt.ai/reference/customgptai-mcp-support#/) for Claude web, Claude Desktop, Cursor, ChatGPT, Windsurf, Trae, etc * [OpenAI Compatibility](https://docs.customgpt.ai/reference/customgptai-openai-sdk-compatibility#/) with CustomGPT.ai RAG API and SDK * Real-time streaming responses * 1400+ file format support * [**100+ Integrations**](https://customgpt.ai/integrations/) : Including Google Drive, Dropbox, SharePoint, HubSpot, Salesforce, WordPress, Shopify, Slack, Notion
**API Base URL:** [`https://app.customgpt.ai/api/v1/`](https://app.customgpt.ai/api/v1/)
### **1. Core Agent Management** ``` POST /projects # Create agent (sitemap/file upload) GET /projects # List agents (paginated, 10/page) DELETE /projects/{projectId} # Delete agent permanently GET /projects/{projectId}/settings # Get agent configuration ``` ### **2. Data Source Management** ``` POST /projects/{projectId}/sources # Add data sources PUT /projects/{projectId}/sources/{sourceId}/instant-sync # Sync sitemap DELETE /projects/{projectId}/pages/{pageId} # Remove specific page ``` ### **3. Conversation Management** ``` POST /projects/{projectId}/conversations # Create conversation GET /projects/{projectId}/conversations # List conversations POST /projects/{projectId}/conversations/{sessionId}/messages # Send message ``` ### **4. Analytics & Citations** ``` GET /projects/{projectId}/reports/analysis # Analytics data GET /projects/{projectId}/citations/{citationId} # Citation metadata ``` ### **5. OpenAI Compatibility (Beta)** ``` POST /projects/{project_id}/chat/completions # OpenAI-compatible endpoint ``` **Note:** "Projects" in API = "Agents" in UI (backward compatibility) ## **Authentication** ``` Authorization: Bearer YOUR_API_KEY ``` **Get all the endpoints here -[API Docs](https://docs.customgpt.ai/reference/get_api-v1-projects-projectid-pages#/)** ## Get API Key **Setup:** 1. Login → My Profile → API tab 2. Click "Create API Key" 3. Store securely (one-time view) **Security Features:** * Bearer token authentication * Project-scoped access * SSL/TLS encryption in transit * 256-bit AES encryption at rest * SOC 2 Type 2 certified
## API and SDK Examples Get the entire [CustomGPT.ai](http://CustomGPT.ai) API endpoint to play with here on our [public postman collection](https://www.postman.com/customgpt/workspace/customgpt-ai-api-public-postman-collection/collection/45406715-d9c23d90-578f-43c3-9092-2da58006a76a?action=share\&creator=45406715). | 1 | [Add\_a\_file\_to\_an\_existing\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Add_a_file_to_an_existing_project.ipynb) | | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2 | [Add\_a\_sitemap\_to\_an\_existing\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Add_a_sitemap_to_an_existing_project.ipynb) | | 3 | [Create\_Bot\_By\_File.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Create_Bot_By_File.ipynb) | | 4 | [Create\_Bot\_By\_Sitemap.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Create_Bot_By_Sitemap.ipynb) | | 5 | [Create\_a\_new\_conversation\_and\_send\_a\_message\_to\_the\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Create_a_new_conversation_and_send_a_message_to_the_conversation.ipynb) | | 6 | [Delete\_a\_page\_from\_the\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Delete_a_page_from_the_project.ipynb) | | 7 | [Delete\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Delete_a_project.ipynb) | | 8 | [GetAndUpdatePageMetadata.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/GetAndUpdatePageMetadata.ipynb) | | 9 | [Get\_Citation\_File.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Get_Citation_File.ipynb) | | 10 | [Get\_Project\_Stats.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Get_Project_Stats.ipynb) | | 11 | [Get\_Settings\_for\_a\_particular\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Get_Settings_for_a_particular_project.ipynb) | | 12 | [Get\_citation\_details.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Get_citation_details.ipynb) | | 13 | [List\_all\_pages\_of\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/List_all_pages_of_a_project.ipynb) | | 14 | [List\_all\_projects\_for\_an\_account\_with\_pagination.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/List_all_projects_for_an_account_with_pagination.ipynb) | | 15 | [Reindex\_page\_of\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Reindex_page_of_a_project.ipynb) | | 16 | [Retrieve\_messages\_for\_a\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Retrieve_messages_for_a_conversation.ipynb) | | 17 | [SDK\_Add\_a\_FIle\_to\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Add_a_FIle_to_project.ipynb) | | 18 | [SDK\_Add\_a\_Sitemap\_to\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Add_a_Sitemap_to_project.ipynb) | | 19 | [SDK\_Create\_Bot\_By\_Sitemap.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Create_Bot_By_Sitemap.ipynb) | | 20 | [SDK\_Create\_a\_new\_conversation\_and\_send\_a\_message\_to\_the\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Create_a_new_conversation_and_send_a_message_to_the_conversation.ipynb) | | 21 | [SDK\_Create\_bot\_from\_file.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Create_bot_from_file.ipynb) | | 22 | [SDK\_Delete\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Delete_a_project.ipynb) | | 23 | [SDK\_Delete\_a\_project\_page.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Delete_a_project_page.ipynb) | | 24 | [SDK\_GetPageMetadata.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_GetPageMetadata.ipynb) | | 25 | [SDK\_Get\_Citation\_Details.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Get_Citation_Details.ipynb) | | 26 | [SDK\_Get\_Project\_Stats.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Get_Project_Stats.ipynb) | | 27 | [SDK\_Get\_settings\_for\_a\_particular\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Get_settings_for_a_particular_project.ipynb) | | 28 | [SDK\_List\_all\_pages\_belonging\_to\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_List_all_pages_belonging_to_a_project.ipynb) | | 29 | [SDK\_List\_all\_projects\_using\_pagination.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_List_all_projects_using_pagination.ipynb) | | 30 | [SDK\_Reindex\_page\_belonging\_to\_a\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Reindex_page_belonging_to_a_project.ipynb) | | 31 | [SDK\_Retrieve\_Messages\_of\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Retrieve_Messages_of_conversation.ipynb) | | 32 | [SDK\_Update\_Delete\_a\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Update_Delete_a_conversation.ipynb) | | 33 | [SDK\_Update\_a\_project\_name.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Update_a_project_name.ipynb) | | 34 | [SDK\_Update\_project\_settings.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Update_project_settings.ipynb) | | 35 | [SDK\_Update\_project\_sharing\_and\_get\_project\_share\_link,\_embed\_code\_and\_chat\_js\_code.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/SDK_Update_project_sharing_and_get_project_share_link%2C_embed_code_and_chat_js_code.ipynb) | | 36 | [Update a project name.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Update%20a%20project%20name.ipynb) | | 37 | [Update\_Delete\_a\_conversation.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Update_Delete_a_conversation.ipynb) | | 38 | [Update\_project\_sharing\_and\_get\_project\_share\_link,\_embed\_code\_and\_chat\_js\_code.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Update_project_sharing_and_get_project_share_link%2C_embed_code_and_chat_js_code.ipynb) | | 39 | [Update\_settings\_for\_a\_particular\_project.ipynb](https://github.com/Poll-The-People/customgpt-cookbook/blob/main/examples/Update_settings_for_a_particular_project.ipynb) | ## **SDK code snippets** ### **1. Python Installation & Basic Usage** ``` pip install customgpt-client ```
``` from customgpt_client import CustomGPT import uuid # Setup CustomGPT.api_key = "YOUR_API_KEY" # Create agent response = CustomGPT.Project.create( project_name='My AI Agent', sitemap_path='https://example.com/sitemap.xml' ) project_id = response.data.id # Send message session_id = uuid.uuid4() stream_response = CustomGPT.Conversation.send( project_id=project_id, session_id=session_id, prompt="What services do you offer?" ) answer = stream_response.parsed.data.openai_response ```
### **2. Async Operations** ``` response = await CustomGPT.Project.acreate( project_name='Test Agent', sitemap_path='https://example.com/sitemap.xml' ) ``` ### **3. Streaming Responses** ```py # Add ?stream=true to message endpoint stream_response = CustomGPT.Conversation.send( project_id=project_id, session_id=session_id, prompt="Your question", stream=True # Enable real-time streaming ) ``` ### **4. cURL Example** ```shell curl -X POST https://app.customgpt.ai/api/v1/projects -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"project_name": "Test", "sitemap_path": "https://example.com/sitemap.xml"}' ``` ## **Integrations** ## 1. OpenAI SDK Compatibility Drop-in replacement for existing OpenAI applications: ``` from openai import OpenAI client = OpenAI( api_key="CUSTOMGPT_API_KEY", base_url="https://app.customgpt.ai/api/v1/projects/{project_id}/" ) response = client.chat.completions.create( model="gpt-4", # Ignored - uses project's model messages=[{"role": "user", "content": "Hello"}] ) ``` **Limitations:** * Only chat.completions endpoint supported * No token usage metrics * Many parameters ignored (temperature, max\_tokens, etc.) * No embeddings, audio, or fine-tuning support ## 2. Hosted MCP Support **Model Context Protocol for AI Clients:** * **Endpoint:** `https://mcp.customgpt.ai/projects//sse?token=` * **Protocol:** Server-Sent Events (SSE) over HTTPS * **Compatible Clients:** Claude Desktop, Cursor, Windsurf, n8n, Zapier **Claude Desktop Configuration:** ```json { "mcpServers": { "customgpt-mcp-server": { "command": "npx", "args": [ "-y", "supergateway", "--sse", "https://mcp.customgpt.ai/projects//sse", "--header", "Authorization: Bearer " ] } } } ``` **Direct SSE Clients (Cursor/Windsurf):** ```json { "mcpServers": { "customgpt-mcp-server": { "url": "https://mcp.customgpt.ai/projects//sse?token=" } } } ```
### **3. Pre-built Integrations (100+)** * **Cloud Storage:** Google Drive, Dropbox, Box, SharePoint * **Documentation:** Notion, Confluence, GitHub (via API) * **CRM/Support:** HubSpot, Salesforce, Zendesk, Intercom * **CMS/E-commerce:** WordPress, Shopify, Wix, Webflow * **Communication:** Slack, Teams (via Zapier, Connector and API) * **Automation:** Zapier (bi-directional), n8n, Make **More** - [CustomGPT.ai Integrations](https://customgpt.ai/integrations/)
## **Model Support** CustomGPT.ai uses proprietary RAG models optimized for business accuracy: * **Automatic model selection** based on use case * **No manual model configuration** required * **Focus on grounded responses** from your data * **Anti-hallucination algorithms** built-in * **#1 ranked accuracy** in independent benchmarks
**LLM Models:** Use [models](https://docs.customgpt.ai/docs/how-to-choose-the-right-gpt-model-for-your-ai-agent#/) like GPT-4.1-mini, GPT-4.1, or GPT-o4, GPT-o4 mini, Claude 3, 3.5 sonnet.
## **Developer Tools** ## 1. Postman Collection - [LINK](https://www.postman.com/customgpt/workspace/customgpt-ai-api-public-postman-collection/collection/45406715-d9c23d90-578f-43c3-9092-2da58006a76a?action=share\&creator=45406715) * **Public workspace** with all endpoints * **Pre-configured authentication** * **Environment management** (prod/staging) * **Built-in test scripts** * **Fork to sync** with updates
**Import:** 1. Open CustomGPT.ai Postman workspace 2. Fork (don't import) the collection 3. Set jwt\_token in environment 4. Start testing immediately
## 2. GitHub Resources * **Cookbook -[LINK](https://github.com/Poll-The-People/customgpt-cookbook)** * **Examples:** Python SDK usage, personas, integration patterns
## 3. Customer Intelligence & Analytics **Export Capabilities:** * Conversation logs with metrics * JSON, Excel, CSV format [exports](https://docs.customgpt.ai/docs/how-to-download-conversation-history#/) * Real-time data updates * Advanced filtering
**Analytics Features:** * Performance metrics dashboard * [User sentiment analysis](https://customgpt.ai/build-customer-intelligence-tool/) * Intent classification * Content gap identification * Query tracking and monitoring
### **4. Additional Developer Features** **API Capabilities:** * 3-line code integration * Sub-second response configurations * Real-time data ingestion * [Webhook support for events](https://customgpt.ai/customgpt-dialogflow-integration/) * Batch operations * [Rate limiting](https://docs.customgpt.ai/docs/how-to-view-limits-and-usage-1#/) (scales with plan)
**Development Resources:** * Comprehensive API documentation * Sandbox environment for testing * Error handling guides * [58+ step-by-step tutorials \[YouTube\]](https://www.youtube.com/channel/UC8FQFRCUgdoeeAVeXZmVdcw) * [Community Slack channel](https://customgpt.ai/slack) * **Email support**:
**Security & Compliance:** * [Multi-factor authentication](https://docs.customgpt.ai/docs/how-to-enable-2fa-1#/) (MFA) * [**GDPR Compliant**](https://customgpt.ai/gdpr-compliance/) **Read [more](https://docs.customgpt.ai/docs/is-customgptai-gdpr-compliant#/)** * Enterprise-grade infrastructure that can autoscale when needed. * Data isolation between agents
That’s the wrap for this little guide highlighting our API capabilities. See you around.