API Reference
Start typing to search…

API Keys and Authentication

To start using CustomGPT's API, authentication via API keys is essential.

How to Generate Your API Key

Generating your API key is the first step towards unlocking the full potential of CustomGPT and AI for you and your knowledge base. To generate your first API key, log in to our platform and navigate to My Profile, which is reachable by clicking the top right circle on the CustomGPT app page and selecting My Profile.

For help logging in or creating your account, visit ourguides.

From there, select the API tab, where you will find a Create API Key button at the bottom of the page.

🚧

Attention

Take note of your API key during the generation process, as it will be hidden once you leave the page.

Additionally, make sure to keep your API key private to prevent unauthorized access and data breaches!

Why Use API Keys?

API keys are vital for ensuring that only authorized users can access our services, providing a secure way to authenticate and monitor interactions with our API. By using API keys, we can efficiently manage and control access, enabling us to offer each user a more personalized and secure experience. Additionally, API keys help in tracking usage patterns, which assists in optimizing and improving our services.

Best Practices

To maximize the security of your API interactions, here are some best practices:

  • Secure Transmission: Always ensure that API keys are transmitted over HTTPS to safeguard against interception.
  • Permission Limitation: Use API keys with minimal permissions necessary for the tasks at hand to minimize potential risks.
  • Key Management: Regularly update and promptly deactivate old or compromised API keys.
  • Usage Monitoring: Keep an eye on API key usage to quickly identify and respond to any unusual activity.
  • Safe Storage: Avoid embedding API keys directly in your code. Instead, store them in secure, server-side environments or configuration files that are excluded from version control systems.

Requests and Responses

With CustomGPT, you can use a wide variety of programming languages to make HTTP requests for our API.

Generating an Agent

To make your first call, you can copy and paste the below code to create a new Agent called "Test", but you will need to replace "sitemap.com" with your actual desired sitemap, and "APIKey_Here" with your actual API key.

curl --request POST \
     --url https://app.customgpt.ai/api/v1/projects \
     --header 'accept: application/json' \
     --header 'authorization: Bearer APIKey_Here' \
     --header 'content-type: multipart/form-data' \
     --form project_name=Test \
     --form sitemap_path=sitemap.com

Sending Messages

Once you have generated your first agent, it will receive an associated ID. This will be your key to sending a message to your Agent via our API.

Creating a Conversation

First, you must create a Conversation within the Agent. Below, replace 'projectID' with the ID of your new Agent, and 'APIKey_Here' with your actual API key.

curl --request POST \
     --url https://app.customgpt.ai/api/v1/projects/projectID/conversations \
     --header 'accept: application/json' \
     --header 'authorization: Bearer APIKey_Here' \
     --header 'content-type: application/json'
     --data '{"name":"Test_Conversation_Name"}'

Sending a Message to the Conversation

Once you have created a Conversation, you can get started by sending a message in that Conversation. In the below example, replace 'projectID' with the ID of your new Agent, 'sessionID' with the session ID of the Conversation created, and 'APIKey_Here' with your actual API key.

curl --request POST \
     --url https://app.customgpt.ai/api/v1/projects/projectID/conversations/sessionID/messages \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_key_Here' \
     --header 'content-type: application/json' \
     --data '{"prompt":"Hello!"}'

Edit Settings to Enable Streaming

Want to see your answer generated in real-time, piece by piece? Try enabling streaming. You can enable streaming by changing the URL line in the previous snippet to add '?stream=true' to the end:

     --url https://app.customgpt.ai/api/v1/projects/projectID/conversations/sessionID/messages?stream=true \

Here's what a sample streaming output would look like:

event: start
data: {"status":"start","prompt":"Hello!"}

event: progress
data: {"status":"progress","message":""}

event: progress
data: {"status":"progress","message":"Hello"}

event: progress
data: {"status":"progress","message":"!"}

event: progress
data: {"status":"progress","message":" How"}

event: progress
data: {"status":"progress","message":" can"}

event: progress
data: {"status":"progress","message":" I"}

event: progress
data: {"status":"progress","message":" assist"}

event: progress
data: {"status":"progress","message":" you"}

event: progress
data: {"status":"progress","message":" today"}

event: progress
data: {"status":"progress","message":"?"}

event: finish
data: {"status":"finish","id":2495484,"created_at":"2024-05-23T03:12:49.000000Z","session_id":"99722e7b-9f6d-4f29-8fcf-aae2566e89e8","citations":null}

Parsing the streamed message and compiling it into a full response has many nuances and should be approached with caution. We have examples in our cookbook if you wish to learn more.

We also offer the ability to query and receive responses from your CustomGPT agents without streaming. Your output can be expected to look something like this for a non-streamed answer from your CustomGPT chatbot:

{
  "data": {
    "id": 2495484,
    "created_at": "2024-05-23T03:12:49.000000Z",
    "updated_at": "2024-05-23T03:12:49.000000Z",
    "user_id": 1408827,
    "user_query": "Hello!",
    "openai_response": "Hello! How can I assist you today?",
    "citations": null,
    "metadata": {
      "user_ip": "IP_Address",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
      "external_id": "",
      "request_source": "api"
    }
  },
  "status": "success"
}