Chamelingo API Documentation

End-to-end tutorial — create a Korean study bot that chats, manages flashcards, and tracks progress.

This guide walks through building a complete Korean study bot using the Chamelingo API. By the end, your bot will:

Chat with the AI tutor
Create flashcard decks from conversations
Review cards using spaced repetition
Track learning progress

Prerequisites#

Create an API key with scopes: tutor, decks, progress.

bash

curl -X POST https://api.chamelingo.com/api/v1/keys \
  -H "Cookie: better-auth.session_token=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "Study Bot", "scopes": ["tutor", "decks", "progress"]}'

Step 1: Chat with the Tutor#

Ask the tutor to teach vocabulary on a topic:

bash

curl -N -X POST https://api.chamelingo.com/api/v1/chat \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"message": "Teach me 5 Korean words for ordering food at a restaurant"}'

Python

import requests

response = requests.post(
    "https://api.chamelingo.com/api/v1/chat",
    headers={"Authorization": "Bearer ck_live_YOUR_KEY_HERE"},
    json={"message": "Teach me 5 Korean words for ordering food at a restaurant"},
    stream=True,
)

conversation_id = None
for line in response.iter_lines():
    if line:
        data = line.decode()
        if '"type":"done"' in data:
            import json
            parsed = json.loads(data.split("data: ")[1])
            conversation_id = parsed["conversation_id"]

TypeScript

const response = await fetch("https://api.chamelingo.com/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer ck_live_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Teach me 5 Korean words for ordering food at a restaurant",
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let conversationId: string | null = null;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  if (text.includes('"type":"done"')) {
    const data = JSON.parse(text.split("data: ")[1]);
    conversationId = data.conversation_id;
  }
}

Parse the SSE stream and save the conversation_id from the done event.

Step 2: Create a Flashcard Deck#

bash

curl -X POST https://api.chamelingo.com/api/v1/decks \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: food-deck-v1" \
  -d '{"title": "Restaurant Korean", "description": "Food ordering vocabulary"}'

Python

response = requests.post(
    "https://api.chamelingo.com/api/v1/decks",
    headers={
        "Authorization": "Bearer ck_live_YOUR_KEY_HERE",
        "Idempotency-Key": "food-deck-v1",
    },
    json={
        "title": "Restaurant Korean",
        "description": "Food ordering vocabulary",
    },
)
deck_id = response.json()["id"]

TypeScript

const response = await fetch("https://api.chamelingo.com/api/v1/decks", {
  method: "POST",
  headers: {
    Authorization: "Bearer ck_live_YOUR_KEY_HERE",
    "Content-Type": "application/json",
    "Idempotency-Key": "food-deck-v1",
  },
  body: JSON.stringify({
    title: "Restaurant Korean",
    description: "Food ordering vocabulary",
  }),
});
const { id: deckId } = await response.json();

Step 3: Import Cards#

Extract vocabulary from the tutor's response and import them:

bash

curl -X POST https://api.chamelingo.com/api/v1/decks/DECK_ID/cards/import \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: food-import-v1" \
  -d '{
    "cards": [
      {"front": "메뉴", "back": "Menu", "phonetic": "menyu", "tags": ["food"]},
      {"front": "주문하다", "back": "To order", "phonetic": "jumunhada", "tags": ["food"]},
      {"front": "계산서", "back": "Bill/Check", "phonetic": "gyesanseo", "tags": ["food"]},
      {"front": "맛있다", "back": "Delicious", "phonetic": "masitda", "tags": ["food"]},
      {"front": "물", "back": "Water", "phonetic": "mul", "tags": ["food"]}
    ]
  }'

Step 4: Review Due Cards#

Check which cards are due for review:

bash

curl "https://api.chamelingo.com/api/v1/decks/DECK_ID/cards/review?limit=10" \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

Step 5: Submit Review Results#

After the user reviews cards, submit their ratings:

bash

curl -X POST https://api.chamelingo.com/api/v1/reviews \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {"card_id": "card_abc", "rating": 3},
      {"card_id": "card_def", "rating": 4},
      {"card_id": "card_ghi", "rating": 1}
    ]
  }'

Ratings follow the FSRS-5 scale: 1 = Again, 2 = Hard, 3 = Good, 4 = Easy.

Step 6: Track Progress#

bash

curl https://api.chamelingo.com/api/v1/progress/summary \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

The response includes XP, level, current streak, hearts, and overall stats — everything your bot needs to show learning progress.

Putting It Together#

A typical study session flow:

GET /progress/summary — show the user their stats
GET /decks — list their decks
GET /decks/:id/cards/review — get due cards
Present cards to the user, collect ratings
POST /reviews — submit results
POST /chat — ask the tutor for help on missed words
Repeat daily

Tip

Use the Idempotency-Key header on all POST requests to safely handle retries. If your bot crashes mid-import, replaying the same request won't create duplicates.

Building a Study Bot