Curriculum Taxonomy API for Indian and international boards

What teams build on the taxonomy

Model your content against stable taxonomy IDs rather than free text. Store the Gyanis topic ID on each lesson, question or progress row, then call GET /taxonomy/topics/:topicId or POST /taxonomy/topics/resolve to render names on demand. When a syllabus changes, GET /taxonomy/changes tells you exactly which records changed or were deleted.

curl -X POST "https://api.gyanis.ai/platform/v1/taxonomy/topics/resolve" \
  -H "Authorization: Bearer gyn_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  -H "Content-Type: application/json" \
  -d '{"topicIds":["652f1a9c4b7d3e0012ab34cd","652f1a9c4b7d3e0012ab34a1","652f1a9c4b7d3e0012ab34b2"]}'

{
  "object": "taxonomy.topic_contexts",
  "contexts": [
    {
      "topic_id": "652f1a9c4b7d3e0012ab34cd",
      "topic_name": "Refraction of Light",
      "unit_id": "652f1a9c4b7d3e0012ab2f88",
      "unit_name": "Optics",
      "subject_id": "652f1a9c4b7d3e0012ab1e77",
      "subject_name": "Physics",
      "grade_id": "652f1a9c4b7d3e0012ab0d66",
      "grade_label": "Class 10",
      "board_id": "652f1a9c4b7d3e0012ab0155",
      "board_name": "Central Board of Secondary Education",
      "board_code": "CBSE",
      "country": "IN",
      "canonical_path": "CBSE > Class 10 > Physics > Optics > Refraction of Light",
      "learning_objectives": ["State the laws of refraction of light"],
      "keywords": ["refractive index", "Snell's law"],
      "difficulty": 3
    }
  ],
  "missing": [],
  "billing": {
    "request_units": 3,
    "free_units_applied": 0,
    "credits_charged": 300,
    "estimated_usd": 0.003,
    "test_mode": false
  }
}

How do I integrate the Gyanis Taxonomy API?

Create an API key carrying the taxonomy scope, then walk the hierarchy from a country board list down to a topic, fetch that topic’s context, and pass it into a chat request. The eleven steps below are one continuous story: grounding an AI tutor in the CBSE Class 10 Physics syllabus.

export GYANIS_KEY="gyn_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
export BASE="https://api.gyanis.ai/platform/v1"

curl -H "Authorization: Bearer $GYANIS_KEY" "$BASE/taxonomy/boards?country=IN"
curl -H "Authorization: Bearer $GYANIS_KEY" "$BASE/taxonomy/boards/$BOARD_ID/grades"
curl -H "Authorization: Bearer $GYANIS_KEY" "$BASE/taxonomy/grades/$GRADE_ID/subjects"
curl -H "Authorization: Bearer $GYANIS_KEY" "$BASE/taxonomy/subjects/$SUBJECT_ID/units"
curl -H "Authorization: Bearer $GYANIS_KEY" "$BASE/taxonomy/units/$UNIT_ID/topics"

const BASE = 'https://api.gyanis.ai/platform/v1';
const auth = { Authorization: `Bearer ${process.env.GYANIS_KEY}` };

// 1. Enriched read — 400 credits. Returns the topic's LLM-ready context.
const res = await fetch(`${BASE}/taxonomy/topics/${topicId}/context`, { headers: auth });
const { context, billing } = await res.json();

// 2. Ground the tutoring call in that context.
await fetch(`${BASE}/chat`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'mobius',
    entity_id: 'student_8842',
    messages: [
      {
        role: 'system',
        content: [
          `Answer only within: ${context.canonical_path}`,
          `Learning objectives: ${context.learning_objectives.join('; ')}`,
        ].join('\n'),
      },
      { role: 'user', content: 'Why does a pencil look bent in water?' },
    ],
  }),
});

console.log(billing.credits_charged); // 400

The topic context payload

GET /taxonomy/topics/:topicId/context returns one LLM-ready block for a single topic, nested under a context key: canonical path, board, grade, subject and unit, learning objectives, prerequisites with their topic IDs, keywords, difficulty from 1 to 5, sample prompts and tags. It is an enriched read at $4.00 per 1,000 requests.

curl "https://api.gyanis.ai/platform/v1/taxonomy/topics/652f1a9c4b7d3e0012ab34cd/context" \
  -H "Authorization: Bearer gyn_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"

{
  "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": [
      "State the laws of refraction of light",
      "Apply Snell's law to solve numerical problems",
      "Explain refraction through a rectangular glass slab"
    ],
    "prerequisites": ["Reflection of Light", "Light: basic properties"],
    "prerequisite_topic_ids": ["652f1a9c4b7d3e0012ab34a1", "652f1a9c4b7d3e0012ab34b2"],
    "prerequisite_topic_names": ["Reflection of Light", "Light: basic properties"],
    "keywords": ["refractive index", "Snell's law", "optical density", "lateral displacement"],
    "difficulty": 3,
    "sample_prompts": [
      "Explain why a pencil appears bent when partially immersed in water.",
      "A ray of light passes from air into glass at 45 degrees. Find the angle of refraction if n = 1.5."
    ],
    "tags": ["optics", "numericals", "board-exam"]
  },
  "billing": {
    "request_units": 1,
    "free_units_applied": 0,
    "credits_charged": 400,
    "estimated_usd": 0.004,
    "test_mode": false
  }
}

A request unit is one billable item: one API call, or one topic ID inside a batch resolve. Every single-call endpoint is exactly one request unit, basic and enriched alike. The rate class sets what that unit costs — 100 credits for a basic read, 400 for an enriched one — and the billing object above reports it per call. Full request and response reference for all 13 endpoints lives in the API documentation.

Endpoint reference

The Gyanis Taxonomy API exposes 13 endpoints under https://api.gyanis.ai/platform/v1, and all of them are read-only — the single POST is a batch lookup, not a write. 7 are basic reads at $1.00 per 1,000 requests, 4 are enriched reads at $4.00 per 1,000, one is that batch resolve billed per topic ID, and one is the bulk-export add-on.

What each endpoint returns, its parameters, request bodies and full response samples are in the API documentation. GET /taxonomy/export is the one add-on: it needs the taxonomy.export scope plus account-level activation.

Is there an API for JEE and NEET topic weightage?

Yes. The Gyanis Taxonomy API exposes exam tracks: GET /taxonomy/exam-tracks?country=IN lists them, and GET /taxonomy/exam-tracks/:trackId?withTopics=true returns the exam’s sections, marks, negative-marking rules, sittings and per-topic weightage mapped to curriculum topics. The basic exam-track list is $1.00 per 1,000 requests; exam-track detail is an enriched read at $4.00 per 1,000.

GET https://api.gyanis.ai/platform/v1/taxonomy/exam-tracks/665f1c2ab8f4a21d3c9e1b07?withTopics=true
Authorization: Bearer gyn_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

200 OK
{
  "object": "taxonomy.exam_track",
  "exam_track": {
    "id": "665f1c2ab8f4a21d3c9e1b07",
    "code": "JEE_MAIN",
    "name": "JEE Main",
    "country": "IN",
    "format": "mcq",
    "total_time_min": 180,
    "sittings": [
      { "series": "Session 1", "year": 2027, "exam_date": "2027-01-24T00:00:00.000Z", "registration_deadline": "2026-11-30T00:00:00.000Z" }
    ],
    "sections": [
      { "paper": "Paper 1", "name": "Physics", "code": "PHY-A", "question_types": ["MCQ"], "marks": 4, "negative": -1, "duration_min": 60, "count": 20 }
    ],
    "updated_at": "2026-08-10T08:12:33.000Z"
  },
  "coverage": [
    {
      "topic_id": "652f1a9c4b7d3e0012ab34cd",
      "weight_percent": 6.5,
      "question_types": ["MCQ"],
      "difficulty_dist": [],
      "subject_id": "652f1a9c4b7d3e0012ab1e77",
      "section_code": "PHY-A",
      "topic": { "id": "652f1a9c4b7d3e0012ab34cd", "name": "Refraction of Light", "slug": "refraction-of-light" }
    }
  ],
  "billing": { "request_units": 1, "free_units_applied": 0, "credits_charged": 400, "estimated_usd": 0.004, "test_mode": false }
}

How do I keep my copy of the syllabus up to date?

Call GET /taxonomy/changes?since=<ISO timestamp> for cursor-paginated deltas, including tombstones for deleted records, over a rolling 180-day window. Subscribe to the taxonomy.updated webhook (debounced, roughly 60 seconds) so you only poll when something actually changed. Changes is an enriched read at $4.00 per 1,000 requests; Gyanis maintains the syllabi.

A syllabus that changes is the reason curriculum data rots, so Gyanis treats maintenance as the product. Subscribe once — see webhook subscriptions — and taxonomy.updated tells you when something moved while GET /taxonomy/changes tells you exactly what.

GET https://api.gyanis.ai/platform/v1/taxonomy/changes?since=2026-08-01T00:00:00Z&types=unit,topic&limit=100
Authorization: Bearer gyn_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

200 OK
{
  "object": "taxonomy.changes",
  "since": "2026-08-01T00:00:00.000Z",
  "window_days": 180,
  "changes": [
    { "type": "unit",  "id": "652f1a9c4b7d3e0012ab2f88", "change": "deleted",  "name": "Optics (legacy)",     "changed_at": "2026-08-09T11:40:55.312Z" },
    { "type": "topic", "id": "652f1a9c4b7d3e0012ab34cd", "change": "upserted", "name": "Refraction of Light", "changed_at": "2026-08-09T11:42:07.884Z" }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJ0aSI6NCwicGgiOjAsInUiOiIyMDI2LTA4LTA5VDExOjQyOjA3Ljg4NFoiLCJpIjoiNjUyZjFhOWM0YjdkM2UwMDEyYWIzNGNkIn0",
  "billing": { "request_units": 1, "free_units_applied": 0, "credits_charged": 400, "estimated_usd": 0.004, "test_mode": false }
}

How much does the Gyanis Taxonomy API cost?

The Gyanis Taxonomy API is billed per request from the same prepaid credit wallet as Gyanis chat. Basic reads cost $1.00 per 1,000 requests at 100 credits each, and enriched reads — topic context, search, exam-track detail and change deltas — cost $4.00 per 1,000 requests at 400 credits each. The first 10,000 request units each month are free.

What is a curriculum taxonomy?

A curriculum taxonomy is a structured, machine-readable hierarchy of what a school system teaches. The Gyanis Taxonomy API models it as five levels — Board, Grade, Subject, Unit, Topic — with stable IDs at every level, plus exam tracks that map topics to exam sections and weightage. It replaces hard-coded syllabus lists in application code.

Curriculum taxonomy

A curriculum taxonomy is a structured, machine-readable hierarchy of what a school system teaches. The Gyanis Taxonomy API models it as five levels — Board, Grade, Subject, Unit, Topic — with stable IDs at every level.

Board

A board is the authority that defines and examines a curriculum. In the Gyanis Taxonomy API a board is the root of the hierarchy and is scoped to a country, so CBSE and Cambridge IGCSE are separate boards.

Grade

A grade is a year of study within a board. The Gyanis Taxonomy API returns grades using the board’s own naming, so CBSE returns Class 10 rather than a normalised year number.

Subject

A subject is a field of study offered at a grade. The Gyanis Taxonomy API reads subjects from the grade rather than from a global list, because the offer differs by board and by year.

Unit

A unit is the chapter-level grouping a syllabus uses to organise a subject. In the Gyanis Taxonomy API a unit is the natural level for scheduling, coverage reporting and analytics rollups.

Topic

A topic is the teachable leaf node of the curriculum. In the Gyanis Taxonomy API the topic ID is the stable join key you store on lessons, questions and progress rows.

Canonical path

A canonical path is the full board-to-topic address of a topic written as one string. The Gyanis Taxonomy API formats it as "CBSE > Class 10 > Physics > Optics > Refraction of Light" and returns it on the topic context endpoint.

Exam track

An exam track is a description of a competitive exam’s format. The Gyanis Taxonomy API returns sections, marks, negative marking and sittings for JEE/NEET-style exams, together with the curriculum topics each section draws on.

Topic weightage

Topic weightage is how much of an exam a given topic accounts for. The Gyanis Taxonomy API attaches weightage to topics through exam tracks, so a study plan can allocate time by what the exam actually weights.

Request unit

A request unit is one billable item — one API call, or one topic ID inside a batch resolve. Basic calls cost 100 credits per unit and enriched calls 400; the first 10,000 request units each month are free.

Basic read

A basic read is a plain hierarchy or detail lookup. In the Gyanis Taxonomy API basic reads cost 100 credits — $1.00 per 1,000 requests — and cover boards, grades, subjects, units, topic detail and the exam-track list.

Enriched read

An enriched read returns derived or cross-cutting data. In the Gyanis Taxonomy API enriched reads cost 400 credits — $4.00 per 1,000 requests — and cover topic context, search, exam-track detail and change deltas.

Change delta

A change delta is the set of records that changed since a timestamp. The Gyanis Taxonomy API serves deltas from GET /taxonomy/changes with cursor pagination over a rolling 180-day window.

Tombstone

A tombstone is a record that marks a deletion rather than a value. The Gyanis Taxonomy API includes tombstones in change deltas so a local mirror can remove records instead of silently keeping them.

Test mode

Test mode is a key mode that exercises the real API without billing. Gyanis test-mode keys are never charged, and every Taxonomy API response reports test_mode inside its billing object.