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="#8b5cf6"
  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`	`#818cf8`	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
`data-api-key`	-	API key - required for local dev (localhost), not needed in production

Local Development

On localhost, the widget cannot verify your domain via Origin header. Add your API key so it can load your app's config:

<script
  src="https://sparkbrain.app/chat.js"
  data-domain="myapp.com"
  data-api-key="sk_live_..."
></script>
<!-- Remove data-api-key in production - not needed when deployed -->

Your API key is available in the dashboard under the API tab.

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.