Documentation

Add AI chat to your app in minutes

Quick Start

Get AI chat running on your website in 3 steps:

Sign in with Google

Click "Get Started" on the homepage to sign in.

Register your app

Add your app in the dashboard. You'll get an API key like:

spark_ai-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Add the widget

Paste this before </body>:

<script src="https://sparkbrain.app/chat.js"></script>

The widget uses domain-based auth - no API key needed in the client!

Registration

Create your SparkAI account in seconds:

Click "Get Started" or "Sign In" on the homepage
Authenticate with your Google account
Add your app (name + domain) in the dashboard
Copy your API key (shown once!)

Localhost is automatically allowed for development. Your API key is for server-side use only.

Widget Installation

Add the chat widget to any website with a single script tag:

HTML

<script src="https://sparkbrain.app/chat.js"></script>

The widget will appear as a floating button in the bottom-right corner.

Widget Configuration

Customize the widget with data attributes:

<script
  src="https://sparkbrain.app/chat.js"
  data-primary-color="#6366f1"
  data-title="My App"
  data-subtitle="AI Assistant"
  data-position="bottom-right"
  data-greeting="Hi! How can I help?"
></script>

Options

Attribute	Default	Description
`data-primary-color`	`#63638a`	Theme color (hex)
`data-title`	Page title	Header title
`data-subtitle`	AI Assistant	Header subtitle
`data-position`	bottom-right	bottom-right or bottom-left
`data-greeting`	Time-based	Initial greeting message
`data-user-email`	-	User email for context
`data-user-name`	-	User display name

Framework Integration

React

import { useEffect } from 'react';

export function ChatWidget({ user }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://sparkbrain.app/chat.js';
    script.async = true;
    if (user?.email) script.dataset.userEmail = user.email;
    document.body.appendChild(script);
    return () => script.remove();
  }, []);
  return null;
}

Next.js

'use client';
import Script from 'next/script';

export function ChatWidget({ user }) {
  return (
    <Script
      src="https://sparkbrain.app/chat.js"
      strategy="lazyOnload"
      data-user-email={user?.email}
    />
  );
}

REST API

For server-side integration, use the chat endpoint with your API credentials:

POST https://sparkbrain.app/api/chat

Authentication (via Headers)

X-App-ID: your-app-domain.com
X-Api-Key: spark_ai-your-api-key-here

Or pass credentials in the request body (headers take precedence).

Request Body

{
  "messages": ["Hello!", "How are you?"],  // Simple string array
  "appId": "your-app-domain.com",  // Required if not in headers
  "appSecret": "spark_ai-...",     // Required if not in headers
  "model": "llama-3.3-70b-versatile",  // Optional (this is default)
  "userEmail": "user@example.com",     // Optional (for user-level rate limiting)
  "sessionId": "unique-session-id",    // Optional (for conversation history)
  "max_tokens": 150,                   // Optional
  "temperature": 0.7                   // Optional
}

Security: Messages are automatically assigned role: "user" server-side. Clients cannot inject system messages.

Note: userEmail is optional. If omitted, rate limiting applies per-app instead of per-user.

Response

{
  "success": true,
  "response": "Hi! How can I help you today?"
}

Note: Usage and rate limit data are not included in responses to minimize bandwidth. Check your dashboard for detailed analytics and usage tracking.

The widget doesn't need API credentials - it authenticates via your registered domain automatically.

API Examples

cURL (Headers)

curl -X POST https://sparkbrain.app/api/chat \
  -H "Content-Type: application/json" \
  -H "X-App-ID: bottled.email" \
  -H "X-Api-Key: spark_ai-your-api-key-here" \
  -d '{"messages":["Hello!"]}'

JavaScript (Server-side)

const response = await fetch('https://sparkbrain.app/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-ID': 'bottled.email',
    'X-Api-Key': 'spark_ai-your-api-key-here'
  },
  body: JSON.stringify({
    messages: ['Hello!', 'How can you help me?']
  })
});
const data = await response.json();
console.log(data.response);

Python

import requests

response = requests.post(
    'https://sparkbrain.app/api/chat',
    headers={
        'Content-Type': 'application/json',
        'X-App-ID': 'bottled.email',
        'X-Api-Key': 'spark_ai-your-api-key-here'
    },
    json={
        'messages': ['Hello!', 'What can you do?']
    }
)
data = response.json()
print(data['response'])

Alternative: Credentials in Body

curl -X POST https://sparkbrain.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "bottled.email",
    "appSecret": "spark_ai-your-api-key-here",
    "messages": ["Hello!"]
  }'

Playground

Try the chat widget right here! Click the button in the bottom-right corner.

Customize Live Preview

Icon

Color

Title

Subtitle

Position

Rate Limits

Tier	Requests/day
Free	100 per domain
Pro	1,000 per domain

Limits reset at midnight UTC.