Хипотеза
За учители

за_разработчици · версия 1

Публичен програмен интерфейс

Каталогът на „Хипотеза“ като JSON: предмети, класове и теми от учебните програми на МОН и симулациите към тях с връзки. Само за четене, без регистрация и без ключ. Програмният интерфейс не съдържа лични данни – нито на учители, нито на ученици, нито резултати.

Общи правила

  • Адрес на версия 1: https://hipoteza.bg/api/v1
  • Методи: само GET и HEAD. Отговорите са JSON в UTF-8.
  • Достъп от браузър от друг сайт (CORS): разрешен от всеки произход, само за четене и без бисквитки.
  • Кеширане: Cache-Control: public, max-age=3600, stale-while-revalidate=86400 и ETag. Изпратете If-None-Match със стойността на ETag и при непроменени данни ще получите отговор 304 без съдържание.
  • Ограничение: до 120 заявки за 60 секунди от един адрес (за IPv6 – от една мрежа /64). Над него отговорът е 429 със заглавие Retry-After (след колко секунди да опитате пак). Заглавията RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset показват колко заявки остават и след колко секунди лимитът се нулира.
  • Грешките имат вида { "error": { "status": 404, "message": "…" } } със съобщение на български.
  • Версии: в рамките на версия 1 полетата само се добавят. Преименуване или премахване на поле означава нова версия с нов адрес (/api/v2). Полето meta.apiVersion показва версията на схемата, а meta.programmeVersion – версията на учебните програми (v2025-26).

Адреси

GET https://hipoteza.bg/api/v1/catalog

Целият каталог: всеки предмет с класовете му, а всеки клас с темите си – идентификатор, официален номер и заглавие, раздел от програмата, адрес на страницата и идентификаторите на симулациите към темата.

Пример за отговор (съкратен до една тема) 
{
  "meta": {
    "apiVersion": "1",
    "documentation": "https://hipoteza.bg/api",
    "programmeVersion": "v2025-26",
    "programmeStatus": "draft",
    "updatedAt": "2026-10-31",
    "source": "Структурата, заглавията на темите и очакваните резултати са от официалните учебни програми на МОН."
  },
  "subjects": [
    {
      "code": "phy",
      "slug": "fizika",
      "name": "Физика и астрономия",
      "url": "https://hipoteza.bg/fizika",
      "api": "https://hipoteza.bg/api/v1/subjects/phy",
      "grades": [
        {
          "grade": 7,
          "url": "https://hipoteza.bg/fizika/7-klas",
          "topics": [
            {
              "id": "phy-07-T01",
              "number": "1.1",
              "title": "Електричен ток и електрично напрежение",
              "section": {
                "id": "phy-07-S01",
                "title": "Електричен ток"
              },
              "url": "https://hipoteza.bg/fizika/7-klas/elektrichen-tok-i-elektrichno-naprezhenie",
              "simulations": [
                "phy.ohm-law"
              ]
            }
          ]
        }
      ]
    }
  ]
}

GET https://hipoteza.bg/api/v1/subjects/{код}

Един предмет със същата структура и с подробностите на всяка тема: очакваните резултати (поле outcomes) и понятията (поле concepts). Кодове на предметите:

  • phy – Физика и астрономия
  • math – Математика
  • chem – Химия и опазване на околната среда
  • bio – Биология и здравно образование
  • geo – География и икономика
  • hist – История и цивилизации
  • nat – Човекът и природата

Непознат код връща 404.

Пример за отговор (съкратен до една тема) 
{
  "meta": {
    "apiVersion": "1",
    "documentation": "https://hipoteza.bg/api",
    "programmeVersion": "v2025-26",
    "programmeStatus": "draft",
    "updatedAt": "2026-10-31",
    "source": "Структурата, заглавията на темите и очакваните резултати са от официалните учебни програми на МОН."
  },
  "subject": {
    "code": "phy",
    "slug": "fizika",
    "name": "Физика и астрономия",
    "url": "https://hipoteza.bg/fizika",
    "api": "https://hipoteza.bg/api/v1/subjects/phy",
    "grades": [
      {
        "grade": 7,
        "url": "https://hipoteza.bg/fizika/7-klas",
        "topics": [
          {
            "id": "phy-07-T01",
            "number": "1.1",
            "title": "Електричен ток и електрично напрежение",
            "section": {
              "id": "phy-07-S01",
              "title": "Електричен ток"
            },
            "url": "https://hipoteza.bg/fizika/7-klas/elektrichen-tok-i-elektrichno-naprezhenie",
            "concepts": [
              "кулон (С)",
              "електричен ток (I)",
              "ампер (А)",
              "електрично напрежение (U)",
              "волт (V)"
            ],
            "outcomes": [
              {
                "id": "phy-07-T01-O1",
                "text": "Определя тока като електричен заряд, преминал през напречното сечение на проводника за единица време и напрежението като мярка за енергията, която електричните заряди отдават на консуматора или получават от източника.",
                "kind": "skill"
              },
              {
                "id": "phy-07-T01-O2",
                "text": "Измерва електричен ток с амперметър и електрично напрежение с волтметър.",
                "kind": "skill"
              }
            ],
            "simulations": [
              "phy.ohm-law"
            ]
          }
        ]
      }
    ]
  }
}

GET https://hipoteza.bg/api/v1/simulations

Всички симулации: идентификатор, заглавие, кратко описание, предмет, раздел (mon – по учебна програма, lab – свободна лаборатория), класове, теми от текущата версия на програмите, адрес на симулацията и на теоретичната ѝ страница, лиценз и готов текст за посочване на източника.

Пример за отговор (съкратен до една симулация) 
{
  "meta": {
    "apiVersion": "1",
    "documentation": "https://hipoteza.bg/api",
    "programmeVersion": "v2025-26",
    "programmeStatus": "draft",
    "updatedAt": "2026-10-31",
    "source": "Структурата, заглавията на темите и очакваните резултати са от официалните учебни програми на МОН."
  },
  "licence": {
    "id": "CC-BY-SA-4.0",
    "name": "Creative Commons „Признание – Споделяне на споделеното 4.0 Международен“",
    "url": "https://creativecommons.org/licenses/by-sa/4.0/deed.bg"
  },
  "simulations": [
    {
      "id": "phy.ohm-law",
      "title": "Ток, напрежение, съпротивление",
      "description": "Нагласи напрежението и виж как се променя токът. Внимавай да не изгориш крушката!",
      "subject": "phy",
      "section": "mon",
      "grades": [
        7,
        9
      ],
      "topics": [
        "phy-07-T01",
        "phy-07-T02",
        "phy-07-T03"
      ],
      "url": "https://hipoteza.bg/sim/phy.ohm-law",
      "theoryUrl": "https://hipoteza.bg/sim/phy.ohm-law/teoriya",
      "licence": "CC-BY-SA-4.0",
      "attribution": "„Ток, напрежение, съпротивление“ – платформа „Хипотеза“, https://hipoteza.bg/sim/phy.ohm-law, лиценз CC BY-SA 4.0"
    }
  ]
}

Примери

От командния ред:

curl -s https://hipoteza.bg/api/v1/subjects/phy

От JavaScript в браузър или в Node:

const response = await fetch('https://hipoteza.bg/api/v1/catalog');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { meta, subjects } = await response.json();
console.log(meta.programmeVersion, subjects.length);

Лиценз и посочване на източника

Данните за симулациите (заглавия, описания, връзки) се споделят под лиценза Creative Commons „Признание – Споделяне на споделеното 4.0 Международен“ (CC-BY-SA-4.0). Когато ги използвате, посочете източника – за всяка симулация полето attribution съдържа готов текст със заглавието, адреса и лиценза. Структурата, заглавията на темите и очакваните резултати идват от официалните учебни програми на Министерството на образованието и науката.

Вграждайте симулациите с връзка към техния адрес. Програмният интерфейс не дава достъп до профили, класове, игри, домашни или резултати и няма да дава.