Poznámka: Dokumentace je také dostupná jako Markdown soubor.

Rok v ředitelně (RvŘ) - Dokumentace externího API

Vítejte u externího API portálu Rok v ředitelně. Toto API poskytuje přístup pouze pro čtení k datům úkolů napříč všemi vzdělávacími instancemi (ZŠ, MŠ, ZŠMŠ, Zřizovatel).

Základní URL: https://rvr.edu.gov.cz

Autentizace

Všechny API požadavky vyžadují autentizaci pomocí API klíče. Pro získání API klíče kontaktujte správce aplikace RvŘ.

Jak se autentizovat

Přidejte váš API klíč do hlavičky požadavku:

X-API-Key: vas_api_klic

Alternativa: Můžete také použít Authorization hlavičku:

Authorization: Bearer vas_api_klic

Limity požadavků

API klíče mají limity požadavků pro zajištění spravedlivého využití a stability systému. Výchozí limit je 1 000 požadavků za hodinu.

Informace o limitu jsou zahrnuty v hlavičkách odpovědi:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1732395600

Při překročení limitu: 429 Too Many Requests.

Endpointy

1. Získat všechny úkoly

Načte všechny úkoly ze všech instancí.

Endpoint: GET /api/v1/external/tasks

Parametry dotazu (všechny volitelné):

Parametr	Typ	Popis	Příklad
`instance`	string	Filtrovat podle kódu instance	`zs`, `ms`, `zsms`, `zrizovatel`

Ukázkové požadavky:

# Získat všechny úkoly
curl -H "X-API-Key: vas_api_klic" \
https://rvr.edu.gov.cz/api/v1/external/tasks

# Získat pouze úkoly ZŠ
curl -H "X-API-Key: vas_api_klic" \
https://rvr.edu.gov.cz/api/v1/external/tasks?instance=zs

Úspěšná odpověď (200 OK):

{
    "success": true,
    "count": 1247,
    "data": [
{
    "instance_code": "zs",
    "title": "Nastavení organizační struktury",
    "category": "Organizace",
    "priority": "povinne",
    "due_date": "2025-08-31",
    "odkaz1": "https://example.com/dokument1",
    "odkaz2": "",
    "odkaz3": "",
    "notes": "Poznámky k úkolu..."
},
{
    "instance_code": "ms",
    "title": "Vzdělávací program",
    "category": "Vzdělávání",
    "priority": "doporucene",
    "due_date": "2025-09-15",
    "odkaz1": "",
    "odkaz2": "https://example.com/dokument2",
    "odkaz3": "",
    notes": ""
}
    ],
    "meta": {
    "rate_limit": 1000,
    "rate_remaining": 995,
    "rate_reset": 1732395600
    }
}

Pole v odpovědi:

Pole	Typ	Popis
`instance_code`	string	Identifikátor instance (zs, ms, zsms, zrizovatel)
`title`	string	Název úkolu
`category`	string	Kategorie úkolu
`priority`	string	Úroveň priority (povinne, doporucene, zavazne, informativni, vlastni)
`due_date`	string	Termín splnění ve formátu YYYY-MM-DD (může být null)
`odkaz1`	string	URL odkazu 1
`odkaz2`	string	URL odkazu 2
`odkaz3`	string	URL odkazu 3
`notes`	string	Dodatečné poznámky

2. Získat dostupné instance

Načte seznam všech dostupných instancí s počty úkolů.

Endpoint: GET /api/v1/external/instances

Ukázkový požadavek:

curl -H "X-API-Key: vas_api_klic" \ https://rvr.edu.gov.cz/api/v1/external/instances

Úspěšná odpověď (200 OK):

{
"success": true,
"count": 4,
"data": [
    {
        "instance_code": "zs",
        "task_count": 450
    },
    {
        "instance_code": "ms",
        "task_count": 380
    },
    {
        "instance_code": "zsms",
        "task_count": 520
    },
    {
        "instance_code": "zrizovatel",
        "task_count": 220
    }
    ]
}

Chybové odpovědi

Chyby autentizace

Chybějící API klíč (401 Unauthorized):

{
    "success": false,
    "error": {
        "code": "NO_API_KEY",
        "message": "API key is required. Provide it via X-API-Key header or Authorization: Bearer header"
    }
}

Neplatný API klíč (401 Unauthorized):

{
    "success": false,
    "error": {
        "code": "INVALID_API_KEY",
        "message": "API key is invalid or has been revoked"
    }
}

Vypršelý API klíč (401 Unauthorized):

{
    "success": false,
    "error": {
        "code": "API_KEY_EXPIRED",
        "message": "API key has expired"
    }
}

Chyba limitu požadavků

Překročen limit požadavků (429 Too Many Requests):

{
    "success": false,
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Please try again later.",
        "retryAfter": 3456
    }
}

Pole retryAfter udává, kolik sekund je třeba počkat před novým pokusem.

Doporučené postupy

1. Zabezpečte váš API klíč

Nikdy neukládejte API klíče do verzovacího systému
Ukládejte klíče v proměnných prostředí nebo zabezpečené konfiguraci

2. Správa limitů požadavků

Monitorujte hlavičku X-RateLimit-Remaining a implementujte exponenciální prodlevu:

3. Cachování odpovědí

Data úkolů se nemění často, proto implementujte cachování:

Kódy instancí

Kód	Popis
`zs`	Základní škola
`ms`	Mateřská škola
`zsms`	ZŠ + MŠ spojené
`zrizovatel`	Zřizovatel

Úrovně priority

Priorita	Popis
`zavazne`	Závazné
`zavdop`	Závazně-doporučené
`doporucene`	Doporučené
`informativni`	Informativní

Podpora

Pro žádosti o přístup k API, technické problémy nebo dotazy:

Email: rokvreditelne@msmt.gov.cz
Web: https://rvr.edu.gov.cz

Podmínky použití

Přístup k API je poskytován pouze pro účely integrace
Nepokoušejte se obejít limity požadavků
Data nesmí být dále distribuována nebo prodávána
API klíče jsou nepřenosné
Vyhrazujeme si právo odvolat přístup při zneužití

Poslední aktualizace: Prosinec 2025
Protokol: Pouze HTTPS
Formát: JSON