Skip to main content

​
Overview

This quickstart guide will help you integrate the Ilumiera AI B2B API into your application. We’ll walk through getting your API key, ingesting learning sources, and generating educational content.

​
Prerequisites

  • An account at dashboard.getconch.ai TODO:
  • Basic knowledge of HTTP requests and JSON
  • Node.js, Python, or another programming environment

​
Step 1: Get Your API Key

  1. Sign up at dashboard.getconch.ai TODO:
  2. Create your organization in the dashboard
  3. Generate an API key from your dashboard settings
  4. Store it securely - you won’t be able to see it again!
Keep your API key secure! Never expose it in client-side code or public repositories.

​
Step 2: Make Your First API Call

Let’s start by ingesting a learning source. All API calls require your API key in the header: 
curl -X POST "https://b2b-api-backend-95487.ondigitalocean.app/source/ingestSource" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "youtube",
      "userId": "user-123",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "metadata": {
        "topic": "Mathematics",
        "grade": "10th"
      }
    }
  }'

​
Step 3: Ingest Learning Sources

You can ingest various types of learning materials:

​
YouTube Video

const response = await fetch(
  "https://b2b-api-backend-95487.ondigitalocean.app/source/ingestSource",
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      source: {
        sourceType: "youtube",
        userId: "user-123",
        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        metadata: {
          topic: "Mathematics",
          grade: "10th",
        },
      },
    }),
  }
);

const source = await response.json();
console.log("Source ID:", source._id);

​
PDF File Upload

const formData = new FormData();
formData.append("file", pdfFile); // Your PDF file
formData.append(
  "source",
  JSON.stringify({
    sourceType: "file",
    userId: "user-123",
    metadata: {
      topic: "Physics",
      chapter: "Thermodynamics",
    },
  })
);

const response = await fetch(
  "https://b2b-api-backend-95487.ondigitalocean.app/source/ingestSource",
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
    },
    body: formData,
  }
);

const source = await response.json();

​
Step 4: Generate Educational Content

Once you’ve ingested a source, you can generate various types of educational content:

​
Generate Quiz

const quizResponse = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/source/generateQuiz/${sourceId}`,
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: "user-123",
      numberOfQuestions: 10,
      difficulty: "medium",
    }),
  }
);

const { quiz } = await quizResponse.json();
console.log("Quiz generated:", quiz.quiz_name);
console.log("Questions:", quiz.quiz);

​
Generate Flashcards

const flashcardsResponse = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/source/generateFlashcards/${sourceId}`,
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: "user-123",
    }),
  }
);

const { flashcard } = await flashcardsResponse.json();
console.log("Flashcards:", flashcard.flashcards);

​
Generate Mind Map

const mindmapResponse = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/source/generateMindMap/${sourceId}`,
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: "user-123",
    }),
  }
);

const { mindmap } = await mindmapResponse.json();
console.log("Mind map nodes:", mindmap.nodes);
console.log("Mind map edges:", mindmap.edges);

​
Step 5: Retrieve Generated Content

Access previously generated content using their IDs: 
// Get quiz
const quiz = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/quiz/getQuizById/${quizId}`,
  {
    headers: { "api-key": "YOUR_API_KEY" },
  }
).then((res) => res.json());

// Get flashcards
const flashcards = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/flashcard/getFlashCardById/${flashcardId}`,
  {
    headers: { "api-key": "YOUR_API_KEY" },
  }
).then((res) => res.json());

// Get mind map
const mindmap = await fetch(
  `https://b2b-api-backend-95487.ondigitalocean.app/mindmap/getMindMap/${mindmapId}`,
  {
    headers: { "api-key": "YOUR_API_KEY" },
  }
).then((res) => res.json());

​
Complete Example

Here’s a complete example that ties everything together: 
async function processEducationalContent() {
  try {
    // 1. Ingest a YouTube video
    const sourceResponse = await fetch(
      "https://b2b-api-backend-95487.ondigitalocean.app/source/ingestSource",
      {
        method: "POST",
        headers: {
          "api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          source: {
            sourceType: "youtube",
            userId: "user-123",
            url: "https://www.youtube.com/watch?v=educational-video",
            metadata: { topic: "Algebra Basics" },
          },
        }),
      }
    );

    if (!sourceResponse.ok) {
      throw new Error(`Source ingestion failed: ${sourceResponse.status}`);
    }

    const source = await sourceResponse.json();
    console.log("Source ingested:", source._id);

    // 2. Generate quiz
    const quizResponse = await fetch(
      `https://b2b-api-backend-95487.ondigitalocean.app/source/generateQuiz/${source._id}`,
      {
        method: "POST",
        headers: {
          "api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          userId: "user-123",
          numberOfQuestions: 5,
          difficulty: "easy",
        }),
      }
    );

    const { quiz } = await quizResponse.json();
    console.log("Generated quiz with", quiz.quiz.length, "questions");

    // 3. Generate flashcards
    const flashcardsResponse = await fetch(
      `https://b2b-api-backend-95487.ondigitalocean.app/source/generateFlashcards/${source._id}`,
      {
        method: "POST",
        headers: {
          "api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          userId: "user-123",
        }),
      }
    );

    const { flashcard } = await flashcardsResponse.json();
    console.log("Generated", flashcard.flashcards.length, "flashcards");

    return {
      sourceId: source._id,
      quizId: quiz.quiz_id,
      flashcardId: flashcard.flashcard_id,
    };
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

// Run the example
processEducationalContent()
  .then((result) => console.log("Success:", result))
  .catch((error) => console.error("Failed:", error));

​
Error Handling

Always implement proper error handling: 
async function apiRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const errorText = await response.text();
      let errorMessage;

      try {
        const errorJson = JSON.parse(errorText);
        errorMessage = errorJson.error;
      } catch {
        errorMessage = errorText;
      }

      throw new Error(`API Error (${response.status}): ${errorMessage}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Request failed:", error);
    throw error;
  }
}

​
Best Practices

​
Environment Variables

Store your API key in environment variables: 
// .env file
CONCH_AI_API_KEY = your - api - key - here;

// Your application
const apiKey = process.env.CONCH_AI_API_KEY;

​
Rate Limiting

Be mindful of rate limits. Space out requests when generating multiple content types: 
// Add delays between requests
await new Promise((resolve) => setTimeout(resolve, 1000)); // 1 second delay

​
Error Recovery

Implement retry logic for transient failures: 
async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise((resolve) =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

​
Next Steps

  • Explore the API Reference: Check detailed documentation for each endpoint
  • Implement Caching: Cache generated content to reduce API calls
  • Build Your Application: Integrate the API into your educational platform
  • Monitor Usage: Track your API usage in the dashboard

​
Support

For questions or issues: