Camel API Quickstart Guide

camelAI Legacy Product — This documentation covers camelAI’s embedded analytics offering, which is no longer being actively developed. We are migrating existing customers to the new camelAI platform. For the current product, visit camelAI.

Prerequisites

Access to the Camel web console
Basic understanding of REST APIs
A database or data source to connect

Step 1: Generate an API Key

First, you’ll need an API key to authenticate your requests.

Log in to the Camel web console
Navigate to API keys section
Click “Create New API Key”
Copy and securely store your API key - you won’t be able to see it again!

Important: All API requests must include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY

Step 2: Connect a Data Source

You can connect a data source either through the web console or via API.

Option A: Using the Web Console (Recommended for first-time setup)

Navigate to the Data Sources section
Click “Add Data Source”
Select your database type (PostgreSQL, MySQL, Snowflake, etc.)
Fill in the connection details
Test the connection
Save the data source

Option B: Using the API

You can use the unified endpoint to add any supported data source type via API.

See detailed guide for adding a data source via API

Example for adding a PostgreSQL data source:

curl -X POST https://api.camelai.com/api/v1/sources/add/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "POSTGRES",
    "name": "My Production DB",
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp",
    "username": "dbuser",
    "password": "secure_password"
  }'

The response will include your source ID:

{
  "id": 123,
  "name": "My Production DB",
  "type": "postgres",
  "created_at": "2024-01-15T10:00:00Z"
}

Step 3: Add Knowledge Base Entries

Knowledge base entries provide context about your data that helps Camel generate better responses.

Knowledge base massively improves camelAI’s ability to answer questions about your data. This is a must-have for any production application.

You can add knowledge base entries either through the web console (recommended for first-time setup, just like adding data sources) or via the API.

curl -X POST https://api.camelai.com/api/v1/knowledge-base/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": "The orders table contains e-commerce orders. Each order has a unique order_id, customer_id, order_date, and total_amount. Orders with status='cancelled' should be excluded from revenue calculations.",
    "connection_id": 123
  }'

Step 4: Add Reference Queries

Reference queries are pre-written SQL queries that can be used as examples or templates.

Reference queries massively improve camelAI’s ability to answer questions about your data. We recommend adding at least 10 reference queries that capture key metrics that your users are likely to ask.

You can add reference queries through the web console (recommended for first-time setup, just like adding data sources) or via the API.

curl -X POST https://api.camelai.com/api/v1/reference-queries/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Monthly Revenue",
    "query": "SELECT DATE_TRUNC('month', order_date) as month, SUM(total_amount) as revenue FROM orders WHERE status != 'cancelled' GROUP BY 1 ORDER BY 1",
    "source_id": 123
  }'

Step 5: Generate an Iframe

Now you’re ready to create an iframe that your users can interact with. The iframe provides a chat interface where users can ask questions about the connected data.

Understanding UIDs

The uid (user identifier) is a crucial concept:

It can be any string but should be unique for each of your users
All iframes generated with the same uid share conversation history
Use your application’s user ID, email, or any unique identifier
This allows users to continue conversations across different sessions

Creating an Iframe

Note: The knowledge_base_entries and reference_queries parameters in this API call allow you to provide temporary knowledge base entries and reference queries that will only exist for the duration of the iframe session. They are not saved to your persistent knowledge base or reference query list. If you want to add permanent entries, use the web console or the dedicated API endpoints.

See detailed API reference for iframe generation

curl -X POST https://api.camelai.com/api/v1/iframe/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user_123_unique_id",
    "srcs": ["123"],
    "ttl": 900,
    "knowledge_base_entries": ["The orders table contains e-commerce orders..."],
    "reference_queries": [
      {
        "title": "Monthly Revenue",
        "query": "SELECT DATE_TRUNC('month', order_date) as month, SUM(total_amount) as revenue FROM orders WHERE status != 'cancelled' GROUP BY 1 ORDER BY 1"
      }
    ]
  }'

Parameters:

uid: Unique identifier for the user (required)
srcs: Array of data source IDs (required)
ttl: Time-to-live in seconds, 60-3600 (optional, default: 900)
knowledge_base_entries: Additional context (optional)
reference_queries: Example queries (optional)

Response:

{
  "iframe_url": "https://app.camelai.com/iframe/abc123xyz/",
  "cache_key": "abc123xyz",
  "expires_in": 900
}

Step 6: Embed the Iframe

Add the iframe to your application:

<!DOCTYPE html>
<html>
<head>
    <title>Data Analytics Dashboard</title>
</head>
<body>
    <h1>Ask Questions About Your Data</h1>
    
    <iframe 
        src="https://app.camelai.com/iframe/abc123xyz/"
        width="100%"
        height="600"
        frameborder="0"
        allow="clipboard-write">
    </iframe>
</body>
</html>

React Example

import React, { useEffect, useState } from 'react';

function DataChat({ userId }) {
  const [iframeUrl, setIframeUrl] = useState('');

  useEffect(() => {
    async function createIframe() {
      const response = await fetch('https://api.camelai.com/api/v1/iframe/create', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          uid: userId,
          srcs: ['123'],
          ttl: 3600  // 1 hour
        })
      });
      
      const data = await response.json();
      setIframeUrl(data.iframe_url);
    }
    
    createIframe();
  }, [userId]);

  if (!iframeUrl) return <div>Loading...</div>;

  return (
    <iframe 
      src={iframeUrl}
      width="100%"
      height="600"
      frameBorder="0"
      allow="clipboard-write"
    />
  );
}

Best Practices

UID Management: Use consistent UIDs for each user to maintain conversation history
TTL Settings: Balance between security (shorter TTL) and user experience (longer TTL)

Support

For additional help:

API Documentation: https://docs.camelai.com
Support Email: support@camelai.com
Community Forum: https://community.camelai.com

Next Step: Implement Row Level Security

Restrict which rows of your database are visible to each user, based on their unique identifier

General

Quick Start

Row Level Security

Best Practices

Custom Themes

Prerequisites

Step 1: Generate an API Key

Step 2: Connect a Data Source

Option A: Using the Web Console (Recommended for first-time setup)

Option B: Using the API

Step 3: Add Knowledge Base Entries

Step 4: Add Reference Queries

Step 5: Generate an Iframe

Understanding UIDs

Creating an Iframe

Step 6: Embed the Iframe

React Example

Best Practices

Support

Next Step: Implement Row Level Security

​Prerequisites

​Step 1: Generate an API Key

​Step 2: Connect a Data Source

​Option A: Using the Web Console (Recommended for first-time setup)

​Option B: Using the API

​Step 3: Add Knowledge Base Entries

​Step 4: Add Reference Queries

​Step 5: Generate an Iframe

​Understanding UIDs

​Creating an Iframe

​Step 6: Embed the Iframe

​React Example

​Best Practices

​Support

Next Step: Implement Row Level Security

Prerequisites

Step 1: Generate an API Key

Step 2: Connect a Data Source

Option A: Using the Web Console (Recommended for first-time setup)

Option B: Using the API

Step 3: Add Knowledge Base Entries

Step 4: Add Reference Queries

Step 5: Generate an Iframe

Understanding UIDs

Creating an Iframe

Step 6: Embed the Iframe

React Example

Best Practices

Support