Support Try camelAI
Quick Start / Camel API Quickstart Guide

Quick Start

Camel API Quickstart Guide

Step-by-step guide to getting started with the Camel API, including iframe generation, data sources, knowledge base entries, and reference queries.

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.

  1. Log in to the Camel web console
  2. Navigate to API keys section
  3. Click "Create New API Key"
  4. 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.

  1. Navigate to the Data Sources section
  2. Click "Add Data Source"
  3. Select your database type (PostgreSQL, MySQL, Snowflake, etc.)
  4. Fill in the connection details
  5. Test the connection
  6. Save the data source

Option B: Using the API

You can use the unified endpoint to add any supported data source type 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.

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.

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.

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

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

Support

For additional help:

Next Step: Implement Row Level Security

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