​
Camel API Quickstart Guide

This guide will walk you through the essential steps to get started with the Camel API, focusing on 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.camel.ai/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"
}

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.camel.ai/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
  }'

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.camel.ai/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.camel.ai/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 (optional, defaults to all sources)
  • 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.camel.ai/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.camel.ai/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.camel.ai/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)
  3. Knowledge Base: Add comprehensive knowledge base entries to improve response quality
  4. Reference Queries: Include common queries your users might need
  5. Error Handling: Always implement proper error handling for API calls
  6. Security: Never expose your API key in client-side code

​
Next Steps

  • Explore the full API documentation for advanced features
  • Set up webhooks for real-time notifications
  • Implement custom styling for the iframe
  • Use the chat API directly for more control over the conversation flow

​
Troubleshooting

​
Common Issues

  1. 401 Unauthorized: Check your API key is correctly formatted in the Authorization header
  2. 404 Not Found: Verify the endpoint URL and source IDs
  3. Iframe not loading: Ensure the iframe URL hasn’t expired (check TTL)
  4. No data returned: Verify your data source connection and permissions

​
Support

For additional help: