> ## Documentation Index
> Fetch the complete documentation index at: https://camelai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  **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](https://camelai.dev).
</Warning>

## 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](https://console.camelai.com/)
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.

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

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.

* [See detailed guide for adding a data source via API](/api-reference/sources/add-connection)

Example for adding a PostgreSQL data source:

```bash theme={null}
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:

```json theme={null}
{
  "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.

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

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.

* [See detailed guide for adding knowledge base entries via API](/api-reference/knowledge-base/create-knowledge-base-entry)
* [Learn more about Knowledge Base best practices](/dev_api/knowledge-base-guide)

```bash theme={null}
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.

<Warning>
  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.
</Warning>

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

* [See detailed guide for adding reference queries via API](/api-reference/reference-queries/create-reference-query)
* [Learn more about Reference Query best practices](/dev_api/reference-query-guide)

```bash theme={null}
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](/api-reference/iframe/create-iframe-link)

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```html theme={null}
<!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

```jsx theme={null}
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:

* API Documentation: [https://docs.camelai.com](https://docs.camelai.com)
* Support Email: [support@camelai.com](mailto:support@camelai.com)
* Community Forum: [https://community.camelai.com](https://community.camelai.com)

<Card title="Next Step: Implement Row Level Security" icon="lock" href="/dev_api/row-level-security/introduction">
  Restrict which rows of your database are visible to each user, based on their unique identifier
</Card>