Reference

Documentation

Everything you need to embed the chatbot widget or call the RAG API directly from your application.

Generate an API key

Go to API keys or Integration in the sidebar and create a new key. You can optionally lock the key to specific domains (recommended for production widget deployments).

Important: The full key secret is shown only once at creation time. Copy and store it in a safe place — your environment variables, a secrets manager, or your deployment settings.

The key is used in the X-API-Key request header for all chat API calls, and in the data-api-key attribute for the widget.

Embed the chatbot widget

The widget is a single <script> tag loaded from the CDN. It injects a floating chat bubble into the bottom-right corner of your page automatically.

Paste the snippet just before the closing </body> tag. Replace YOUR_PUBLIC_API_KEY with the key you created in Step 1.

html

<!-- VectorBase Chatbot Widget -->
<script
  src="https://vector-base.b-cdn.net/widget.js"
  data-api-key="YOUR_PUBLIC_API_KEY"
  data-api-url="https://easyai.fastapicloud.dev/api/v1"
  defer>
</script>

Widget attributes

Attribute	Required	Description
data-api-key	Yes	Your public API key secret
data-api-url	Yes	Your backend base URL — https://easyai.fastapicloud.dev/api/v1
data-title	No	Widget header title (default: "Support")
data-placeholder	No	Input placeholder text
data-theme	No	"light" or "dark" (default: auto)

Domain locking: If your key was created with allowed domains, the widget will only work on those origins. Add your site URL (e.g. https://my-site.com) when creating the key.

Call the chat API directly

Use POST https://easyai.fastapicloud.dev/api/v1/chat/ to send queries from your own backend or frontend without the widget.

javascript

await fetch('https://easyai.fastapicloud.dev/api/v1/chat/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: 'Where is my order?',
    conversation_id: null,   // null to start a new thread
    use_rag: true,
    use_history: true
  })
})

Response

json

{
  "conversation_id": "conv_a1b2c3d4e5f6",
  "response": "According to your return policy, damaged items can be returned within 30 days..."
}

Field	Type	Description
query	string (required)	The user message or question
conversation_id	string \| null	Pass null to start a new thread; pass the returned ID to continue
use_rag	boolean	Whether to retrieve context from your vector index (default: true)
use_history	boolean	Whether to include conversation history in the prompt (default: true)

Multi-turn conversations

To maintain context across messages, pass the conversation_id returned by the first response back in every subsequent request. The server stores the message history and includes it in the prompt stack automatically when use_history: true.

javascript

// First message — no conversation_id
const res1 = await fetch('https://easyai.fastapicloud.dev/api/v1/chat/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({ query: 'What is your return policy?', use_rag: true, use_history: true })
})
const { conversation_id, response } = await res1.json()

// Follow-up — pass the same conversation_id
const res2 = await fetch('https://easyai.fastapicloud.dev/api/v1/chat/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({ query: 'What about damaged items?', conversation_id, use_rag: true, use_history: true })
})

Each conversation_id is unique per thread. You can retrieve the full transcript later via GET https://easyai.fastapicloud.dev/api/v1/conversations/{}id}.

Session tokens (optional)

If you need to call the chat API from a browser directly without embedding an API key in client-side code, you can exchange your API key for a short-lived session token (15 minutes) first. This keeps the long-lived API key server-side.

javascript

// Exchange API key for a short-lived session token (15 min)
const res = await fetch('https://easyai.fastapicloud.dev/api/v1/auth/session', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
const { access_token } = await res.json()

// Use the session token as Bearer for chat
await fetch('https://easyai.fastapicloud.dev/api/v1/chat/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${access_token}`
  },
  body: JSON.stringify({ query: 'Hello', use_rag: true, use_history: true })
})

Session tokens use the Authorization: Bearer header instead of X-API-Key. Generate a new token server-side before each chat session and pass it to the browser.

Error reference

Status	Meaning	Resolution
400	Bad request	Check that query is non-empty and all required fields are present
401	Invalid or expired key/token	Re-generate the API key or request a new session token
402	Insufficient token balance	Purchase more tokens — available tokens have reached 0
403	Origin not allowed	Add your domain to the key's Allowed Domains list
404	Conversation not found	The conversation_id does not exist or belongs to a different tenant
422	Validation error	A field has the wrong type or is missing — check the request body
500	Server error	Retry after a moment; check your backend logs if self-hosted

API base URL

https://easyai.fastapicloud.dev/api/v1

Configured via NEXT_PUBLIC_API_URL in your environment. Update it to point at your production FastAPI server when deploying.