OpenAI-Compatible RAG
Drop-in replacement for the OpenAI chat completions endpoint — with your YourGPT knowledgebase built in.
Endpoint: POST https://api.yourgpt.ai/chatbot/v1/openai/chat/completions
Change base_url in your OpenAI SDK to point at YourGPT — everything else stays the same. Add a yourgpt:knowledgebase server tool and the endpoint handles retrieval automatically.
from openai import OpenAI
client = OpenAI(
api_key="apk-your-api-key",
base_url="https://api.yourgpt.ai/chatbot/v1/openai",
)
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": "You are a helpful support agent."},
{"role": "user", "content": "What is your refund policy?"},
],
tools=[
{"type": "yourgpt:knowledgebase", "parameters": {"limit": 5}}
],
)
print(response.choices[0].message.content)Authentication
Pass your apk-... project API key as the OpenAI api_key. The SDK sends it as Authorization: Bearer, which YourGPT accepts automatically.
Request limits
| Limit | Value |
|---|---|
| User message length | 5,000 characters |
| Tool round-trips per request | 5 |
model and messages are both required. At least one user message must contain text.
Server tools
Add these to the tools array alongside any of your own OpenAI function tools. Your own tools are passed through to the model unchanged — see User-defined tools.
yourgpt:knowledgebase
Injects a search_knowledgebase function into the LLM. The model calls it when it decides retrieval is needed.
{
"type": "yourgpt:knowledgebase",
"parameters": {
"limit": 5,
"mode": "tool_only"
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 5 | Chunks to retrieve per call. Range: 1–20. |
mode | string | "tool_only" | "tool_only" — model calls the tool on-demand. "hybrid" — YourGPT retrieves relevant context before the model call, and keeps the tool available for follow-ups. |
tool_only — best when the conversation mixes KB and non-KB questions. The model only searches when it decides to.
hybrid — best for always-on KB answers (support bots, FAQ). Context is retrieved up front so the model can answer immediately. Costs slightly more per request.
yourgpt:web_search
Injects a web_search function. The model calls it for live information outside your knowledgebase. Each result includes title, URL, and up to 3,000 chars of text.
{
"type": "yourgpt:web_search",
"parameters": {
"max_results": 5
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
max_results | integer | 5 | Web results per call. Range: 1–25. |
User-defined tools
Any tool in tools[] that isn't a yourgpt:* type is your own tool. YourGPT forwards it to the
model unchanged and, when the model calls it, hands the call back to you exactly as the OpenAI API
would — finish_reason: "tool_calls" with the tool call in the assistant message. Execute it and
POST back the result to continue the conversation.
Knowledgebase and web search run server-side and never appear as tool calls in your response.
If the model calls one of your tools and a server tool in the same turn, the server tool's result is dropped for that turn — the model may request it again on the next turn.
Response
Standard OpenAI response shape plus a sources array.
{
"choices": [{ "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }],
"usage": { "prompt_tokens": 312, "completion_tokens": 48, "total_tokens": 360 },
"sources": [
{
"type": "knowledgebase",
"content": "You can reset your password from...",
"score": 0.921,
"doc_id": "doc_abc123"
},
{
"type": "web",
"title": "EU Consumer Rights",
"url": "https://example.com/eu-consumer-rights",
"text": "Consumers in the EU have..."
}
]
}Every entry is tagged with type — knowledgebase chunks and web results share one array.
type | Fields |
|---|---|
knowledgebase | content, score, doc_id |
web | title, url, text |
sources is empty when nothing was retrieved, and is de-duplicated — the same document or URL appears at most once.
sources is a YourGPT addition to the standard OpenAI response. Typed SDK clients won't expose it
as an attribute — read it from the raw response (e.g. response.model_dump()["sources"] in Python,
or the parsed JSON body in other languages).
Streaming
Set "stream": true — response is standard OpenAI SSE. sources is attached to the final chunk (finish_reason: "stop").
Examples
Rate limits & errors
| Plan | Requests/hr |
|---|---|
| Professional | 200 |
| Advanced / Agency | 1000 |
| Status | error.type | Meaning |
|---|---|---|
| 400 | invalid_request_error | Missing model or messages, no user text, message over 5,000 chars, unsupported model (use gpt-*, o1, or o3), or yourgpt:web_search unavailable |
| 400 | invalid_request_error | Model not available on your plan, or no active subscription |
| 401 | invalid_request_error | Invalid or missing API key (error.code: invalid_api_key) |
| 402 | insufficient_credits | Organization has no remaining credits |
| 429 | rate_limit_error | Hourly limit exceeded |
| 500 | api_error | Internal error, or the model made 5 tool round-trips without finishing |
Errors returned by OpenAI itself are forwarded with their original status and message.