Zero to First Call in 5 Minutes
A step-by-step guide to integrating Gyanis AI into your EdTech product — chat, streaming, per-student tracking and curriculum context. Standard REST API — works with any language or HTTP client.
Prerequisites
- A Gyanis AI account — register here
- An API key from your dashboard (Keys tab)
- No SDK needed — use your language's built-in HTTP client or any HTTP library
Quickstart: chat, streaming and entity tracking
Five steps take you from an empty terminal to a production-ready chat integration. Pick your language above — every sample below follows the selection.
Send Your First Chat Request
Make a POST request to /chat with your API key and a messages array. That's it — a standard REST call.
curl -X POST https://api.gyanis.ai/platform/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{ "role": "user", "content": "What is photosynthesis?" }
],
"model": "mobius",
"entity_id": "student_abc123"
}'{
"id": "req_a1b2c3d4e5f6g7h8i9j0k1l2",
"object": "chat.completion",
"created": 1709834400,
"model": "mobius",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Photosynthesis is the process by which green plants convert sunlight, water, and carbon dioxide into glucose and oxygen..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 185,
"total_tokens": 227
}
}Tip: Use gyn_sk_test_... keys during development — they skip billing while keeping moderation and logging active.
Add Streaming for Real-Time UI
For chat interfaces, use SSE streaming to show tokens as they arrive. Hit the /chat/stream endpoint — same request body, tokens delivered in real-time.
curl -X POST https://api.gyanis.ai/platform/v1/chat/stream \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-N \
-d '{
"messages": [
{ "role": "user", "content": "Explain DNA replication." }
],
"model": "mobius",
"entity_id": "student_abc123"
}'data: {"id":"req_a1b2c3d4e5f6","object":"chat.completion.chunk","created":1709834400,"model":"mobius","choices":[{"index":0,"delta":{"content":"DNA"},"finish_reason":null}]}
data: {"id":"req_a1b2c3d4e5f6","object":"chat.completion.chunk","created":1709834400,"model":"mobius","choices":[{"index":0,"delta":{"content":" replication"},"finish_reason":null}]}
data: {"id":"req_a1b2c3d4e5f6","object":"chat.completion.chunk","created":1709834400,"model":"mobius","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":38,"completion_tokens":210,"total_tokens":248}}
data: [DONE]SSE events: Each data: line contains a chat.completion.chunk object. Append delta.content to your output. data: [DONE] signals stream end. A : ping heartbeat is sent every 15 seconds.
Track Student Conversations with entity_id
Pass entity_id to automatically maintain conversation history per student. The platform stores up to 50 messages — no database needed on your side.
# Turn 1 — ask a question
curl -X POST https://api.gyanis.ai/platform/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{ "role": "user", "content": "What is a variable?" }],
"entity_id": "student_abc123",
"subject": "math",
"grade": "8"
}'
# Turn 2 — follow-up (history auto-included)
curl -X POST https://api.gyanis.ai/platform/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{ "role": "user", "content": "Give me an example." }],
"entity_id": "student_abc123"
}'Add subject and grade for curriculum-aware responses. These cascade from request → entity → tenant config.
Choose Your Model Tier
Pick the model that fits your use case. Set it per-request or configure a default at the tenant level.
Handle Errors Gracefully
All errors return a consistent JSON format. Key codes to handle in production:
insufficient_creditsPrompt user to purchase credits or notify admin
rpm_exceededBack off and retry after Retry-After header seconds
content_policy_violationShow a safe fallback message to the student
model_unavailableRetry with exponential backoff (circuit breaker)
{
"error": {
"code": "insufficient_credits",
"message": "Tenant has insufficient token credits. Remaining: 500.",
"type": "billing_error",
"request_id": "req_a1b2c3d4e5f6g7h8i9j0k1l2"
}
}Curriculum endpoints add three codes of their own: 403 endpoint_not_allowed when the key lacks the taxonomy scope, 403 product_not_enabled when the taxonomy product is switched off for the account (bulk export additionally needs the taxonomy.export scope), and 404 not_found for an unknown board, grade, subject, unit, topic or exam-track ID.
Integrating the Curriculum Taxonomy API
The same key that runs your tutor can also return the syllabus itself. The Gyanis Taxonomy API is a read-only REST API over Board > Grade > Subject > Unit > Topic — thirteen endpoints, twelve of them GET and the one POST a batch lookup rather than a write — and its topic context endpoint is what turns a generic prompt into a syllabus-bounded one. Add the taxonomy scope to your key first.
Add Curriculum Context to a Chat Request
Walk the hierarchy once to reach a topic — boards → grades → subjects → units → topics — then call /taxonomy/topics/:topicId/context for the LLM-ready block. Store the topic ID; it is the stable join key for your lessons, questions and progress rows.
# 1 — list the topics inside a unit (basic read)
curl "https://api.gyanis.ai/platform/v1/taxonomy/units/UNIT_ID/topics" \
-H "Authorization: Bearer YOUR_API_KEY"
# 2 — LLM-ready context for one topic (enriched read)
curl "https://api.gyanis.ai/platform/v1/taxonomy/topics/TOPIC_ID/context" \
-H "Authorization: Bearer YOUR_API_KEY"{
"object": "taxonomy.topic_context",
"topic_id": "652f1a9c4b7d3e0012ab34cd",
"context": {
"canonical_path": "CBSE > Class 10 > Physics > Optics > Refraction of Light",
"country": "IN",
"board_code": "CBSE",
"board_name": "Central Board of Secondary Education",
"grade_code": "10",
"grade_label": "Class 10",
"subject_code": "PHY",
"subject_name": "Physics",
"unit_name": "Optics",
"topic_name": "Refraction of Light",
"learning_objectives": [
"Explain refraction using the change in the speed of light between media",
"Apply Snell's law to a light ray crossing a boundary",
"Relate refractive index to the bending of a ray"
],
"prerequisites": ["Reflection of Light", "Speed of Light"],
"prerequisite_topic_ids": ["652f1a9c4b7d3e0012ab34a1", "652f1a9c4b7d3e0012ab34b2"],
"prerequisite_topic_names": ["Reflection of Light", "Speed of Light"],
"keywords": ["refraction", "Snell's law", "refractive index", "optical density"],
"difficulty": 3,
"sample_prompts": [
"Why does a straw look bent in a glass of water?",
"Derive Snell's law from the change in wave speed"
],
"tags": ["optics", "board-exam"]
},
"billing": {
"request_units": 1,
"free_units_applied": 0,
"credits_charged": 400,
"estimated_usd": 0.004,
"test_mode": false
}
}The context payload nests under context — there is no data envelope — and difficulty is an integer from 1 to 5. The list endpoints return their rows under the name of the level: boards, grades, subjects, units, topics.
Now put that block into a system message on the same /chat request from Step 1. The model still decides how to explain; the taxonomy decides what it is allowed to be about.
{
"model": "mobius",
"entity_id": "student_abc123",
"subject": "physics",
"grade": "10",
"messages": [
{
"role": "system",
"content": "Stay inside this syllabus slot.\nTopic: CBSE > Class 10 > Physics > Optics > Refraction of Light\nObjectives: Explain refraction using the change in the speed of light between media; apply Snell's law.\nPrerequisites: Reflection of Light, Speed of Light."
},
{ "role": "user", "content": "Why does a straw look bent in water?" }
]
}Billing: every call is one request unit. A basic read — any hierarchy walk — costs 100 credits per unit, or $1.00 per 1,000 calls; an enriched read such as topic context costs 400 credits per unit, or $4.00 per 1,000. The first 10,000 request units each month are free — while that allowance lasts the same response reads free_units_applied: 1 and credits_charged: 0. Test-mode keys are never billed, and every response carries the billing object shown above.
Keep Your Curriculum Mirror in Sync
Most teams mirror the tree into their own database for latency and cost, then apply deltas. Syllabi change, so a mirror that is never refreshed silently teaches the wrong syllabus.
Fill once
Walk the hierarchy and write board, grade, subject, unit and topic rows, keyed on the Gyanis IDs.
Subscribe
Turn on the taxonomy.updated webhook — debounced to roughly 60 seconds — so you poll only when something changed.
Pull deltas
On delivery, call /taxonomy/changes with your last timestamp and page through with the returned cursor.
Apply both kinds
Upsert changed records and delete tombstoned ones. The window is a rolling 180 days.
# On taxonomy.updated delivery — pull everything since your last sync
curl "https://api.gyanis.ai/platform/v1/taxonomy/changes?since=2026-08-01T00:00:00Z&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"
# Page through with the cursor the response returns
curl "https://api.gyanis.ai/platform/v1/taxonomy/changes?since=2026-08-01T00:00:00Z&cursor=NEXT_CURSOR" \
-H "Authorization: Bearer YOUR_API_KEY"Full endpoint reference in the API documentation; the use-case walkthrough lives on the Taxonomy API page.
How do I add curriculum context to a Gyanis chat request?
Fetch the topic first, then chat. Call GET /taxonomy/topics/:topicId/context on the Gyanis Taxonomy API, take the canonical path, learning objectives and prerequisites it returns, and put them in a system message on your POST /chat request alongside entity_id, subject and grade. The answer then stays inside that syllabus unit.
How do I keep a local copy of the curriculum in sync?
Mirror the tree once, then apply deltas. Subscribe to the Gyanis taxonomy.updated webhook, which is debounced to roughly sixty seconds, and on delivery call GET /taxonomy/changes?since=&cursor= to page through upserts and delete tombstones over a rolling 180-day window. Changes is an enriched read.