Edu-V API Referentie

Overzicht

Samio neemt deel aan Edu-V (release NR26) als voortgangsdashboard voor leerkrachten. Samio is afnemer van administratiegegevens — onderwijsinrichting, onderwijsdeelnemers, onderwijsmedewerkers en groepen — uit Nederlandse leerlingadministratiesystemen zoals ParnasSys en ESIS, en verzender van de leerresultaten die in de gratis Samio-leerlingapp ontstaan. Samio is geen portaal: er komen geen aanspraken, catalogusgegevens of resultaten binnen.

Inbound — koppelvlakken Samio exposes
/v1/eduv/
├── .well-known/      # OAuth metadata + participation statement
├── oauth/            # Token endpoint + JWKS
├── consent/          # Consent lifecycle (supporting)
├── dpa/              # DPA verification (supporting)
└── notifications/    # Roster-change notifications (we subscribe)

Outbound — koppelvlakken Samio calls at the partner (v1 base)
├── GET  /organisations, /studyofferings/school            # Education 1.1.1
├── GET  /schoolperiods/school, /groups/school,
│        /enrollments/school, /assignments/school         # Association 1.1.0
├── GET  /students/school   POST /students                # Students 1.1.0
├── GET  /employees/school  POST /employees               # Employees 1.1.0
└── POST {v2 base}/results                                # Results 2.1.0 (verzender)

Authenticatie

Alle endpoints vereisen een Bearer-token verkregen via OAuth 2.0 met het NL GOV-profiel (private_key_jwt client-authenticatie).

curl -X POST https://api.samiolearning.com/v1/eduv/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=eyJhbGciOiJSUzI1NiIs..." \
  -d "scope=eduv.student.basic eduv.association"

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "eduv.student.basic eduv.association"
}

{
  "keys": [{
    "kty": "RSA", "kid": "samio-eduv-1", "use": "sig", "alg": "RS256",
    "n": "…", "e": "AQAB",
    "x5c": ["<leaf certificate>", "<issuing CA>", "<intermediate>", "<root>"],
    "x5t": "…", "x5t#S256": "…"
  }]
}

// Header
{ "alg": "RS256", "typ": "JWT", "kid": "samio-eduv-1", "x5c": ["<leaf>", "<issuing CA>", "<intermediate>", "<root>"] }

// Payload
{
  "iss": "<client_id you issued to Samio>",
  "sub": "<client_id you issued to Samio>",
  "aud": "https://auth.example.nl/realms/x/protocol/openid-connect/token",
  "jti": "…256-bit random…",
  "iat": 1761040000,
  "exp": 1761040300
}

// Form body
grant_type=client_credentials
client_id=<client_id you issued to Samio>
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<JWT>
scope=eduv.education eduv.student.basic eduv.employee.basic eduv.association

Foutcodes

{
  "error": "Human-readable error message",
  "error_code": "1001",
  "error_description": "Optional additional details"
}

Paginering

Gepagineerde endpoints accepteren start- en limietparameters.

{
  "data": [ ... ],
  "total": 142,
  "start": 0,
  "limit": 20,
  "hasMore": true
}

Scopes

Beschikbare OAuth 2.0 scopes voor de Edu-V integratie.

Datamodellen

Snel starten

Volledig integratieproces van partnerregistratie tot het uitlezen van resultaten.

Agent-tools (WebMCP)

Tools die AI-agents in de browser op samiolearning.com kunnen aanroepen: vier alleen-lezen tools op elke openbare pagina (prijzen per land, pagina's zoeken, productfeiten, app-links) en, voor een ingelogde leerkracht op het schooldashboard, dezelfde twaalf leerkrachttools als de MCP-server — uitgevoerd met de sessie van de leerkracht.

WebMCP is the W3C-incubated standard (Google + Microsoft) that lets a web page register tools an AI agent running in the browser can call — the page-side counterpart of an MCP server. Every public page on samiolearning.com registers the four tools below once the page has loaded, in browsers that exposenavigator.modelContext. Other browsers pay nothing: the module is loaded at idle and only when the API exists. The tools are deliberately read-only. Nothing submits a form, starts a trial or touches payment; an agent that wants to register a school must hand the person the registration page.

{
  "country": "MX",
  "pricingTier": "tier_b",
  "pricingTierLabel": "Equity — Upper-middle income",
  "discountPercent": 50,
  "currency": "USD",
  "billing": "monthly via PayPal; every plan starts with a 14-day free trial",
  "plans": [
    { "id": "homeschool", "priceUsdPerMonth": 2.49, "standardPriceUsdPerMonth": 4.99, "limits": { "students": 10, "teachers": 1, "classes": 1 } },
    { "id": "classroom",  "priceUsdPerMonth": 9.0,  "standardPriceUsdPerMonth": 19.0, "limits": { "students": 60, "teachers": 1, "classes": 4 } },
    { "id": "school",     "priceUsdPerMonth": 79.0, "standardPriceUsdPerMonth": 159.0, "limits": { "students": 1500, "teachers": "unlimited", "classes": "unlimited" } }
  ],
  "resolvedBy": "api",
  "explanation": "https://samiolearning.com/schools/equity-pricing",
  "register": "https://samiolearning.com/schools/register"
}

{
  "query": "how do i connect google classroom",
  "results": [
    { "title": "Plug Samio into your LMS in 10 minutes", "url": "https://samiolearning.com/schools/integrations", "audience": "schools", "relevance": 7, "description": "…" }
  ]
}

{ "products": [ { "name": "Askimo", "category": "Free educational Wikipedia app for kids ages 4–12", "…": "…" } ], "entityDisambiguation": { "samio": "…", "askimo": "…" }, "source": "https://samiolearning.com/facts.json" }

{ "app": "Askimo", "appStore": "https://apps.apple.com/app/askimo/id6760259046", "googlePlay": "…", "web": "https://samiolearning.com/askimo", "price": "Free, no ads, no accounts", "ages": "4–12", "languages": ["en","es","nl","de","fr","it","pt"] }

Dashboard tools for signed-in teachers

On /schools/dashboard/*, and only while a teacher is signed in, the page additionally registers the twelve teacher tools of the remote MCP server — same names, same input schemas — so a browser agent (Chrome, Gemini in Chrome, Edge Copilot) can do the same work without OAuth: every call runs through the dashboard's own endpoints with the teacher's session, under the same plan limits and consent checks as a click in the UI. The set is withdrawn on logout or when leaving the dashboard; public pages never see it. Generation tools return the new id with status: "generating" and the matching get_ tool polls, exactly as on the MCP server. The schemas are published in the manifest under dashboardTools.

Discovery and testing

• Static manifest of the same tools: /agent-tools.json. Plain-text brief for LLMs: /llms.txt; machine-readable facts: /facts.json.
• In a WebMCP-capable browser (Chrome early preview; enable the WebMCP flag in chrome://flags), open any samiolearning.com page and the tools appear in the browser's agent tool list after load.
• Non-browser agents (an MCP server, a script) do not need WebMCP: the two network-backed tools wrap plain HTTP endpoints you can call directly, shown below.

# Country → pricing tier (public, no auth)
GET https://api.samiolearning.com/v1/schools/pricing/resolve?country=MX
→ { "success": true, "data": { "country": "MX", "pricingTier": "tier_b", "pricingTierLabel": "Equity — Upper-middle income", "pricingDiscountPercent": 50, "currency": "USD" } }

# Canonical product facts
GET https://samiolearning.com/facts.json

# Tool manifest
GET https://samiolearning.com/agent-tools.json

Status: the WebMCP API surface is still changing. The page registers with whichever ofregisterTool() orprovideContext() the browser exposes and silently skips registration otherwise. Tool names and schemas are stable; report problems to info@samiolearning.com.

Remote MCP-server (Samio voor Scholen)

Een remote MCP-server waarmee elke AI-assistent verbinding kan maken — Claude, ChatGPT, Gemini, Claude Code of je eigen agent. Vier alleen-lezen tools voor curriculumdoelen van het basisonderwijs in 50 landen (56 curricula) en de prijzen van Samio voor Scholen werken zonder login; dertien tools voor leerkrachten (materiaal, jaarplannen, uitdagingen, kennisfeiten, dekking op klasniveau) komen beschikbaar zodra een leerkracht zijn of haar Samio voor Scholen-account koppelt met OAuth 2.1. Geen leerlinggegevens, bij geen enkele tool.

The server speaks the Model Context Protocol over Streamable HTTP and is stateless: every request carries what it needs, so it works with any current MCP client. The server lists seventeen tools. The four below need no account: they read the same curriculum spine that grounds every exercise in Samio (50 countries, 56 curricula, seven interface languages) and the public pricing resolver. The other fourteen are teacher tools: they become usable once a teacher connects their Samio for Schools account with OAuth 2.1 and act only inside that teacher's own classes. No tool on either tier returns a student name, score or result, and the gateway behind the server stores only hashed inputs and salted IP hashes for abuse control.

{
  "countries": [
    { "country": "NL", "language": "nl",
      "grades": [ { "gradeLevel": 1, "gradeName": "Groep 3", "ageRange": { "min": 6, "max": 7 } }, … ],
      "subjects": ["math", "reading", "grammar", "science", "physics", "computing"] },
    …
  ]
}

{
  "standard": { "standardId": "…", "country": "NL", "language": "nl", "gradeLevel": 1, "gradeName": "Groep 3",
                "ageRange": { "min": 6, "max": 7 }, "subject": "math",
                "officialName": "Rekenen/Wiskunde — Kerndoelen 23–33 (SLO)",
                "source": { "name": "SLO Kerndoelen Primair Onderwijs", "url": "https://www.slo.nl/…" },
                "assessmentFocus": "Automatiseren van optellen en aftrekken tot 10" },
  "units": [ { "unitId": "NL:math:g1:u:rrw96f", "name": "Optellen en aftrekken tot 20", "description": "…",
               "skills": [ { "skillId": "NL:math:g1:s:lm8mtk", "name": "Sommen tot 10" } ], "matchScore": 0 } ],
  "competencies": [ { "competencyId": "…", "name": "Getalbegrip en getalrelaties" } ],
  "criteria": [ { "criterionId": "…", "text": "Leerlingen kunnen getallen tot 20 lezen, schrijven en ordenen", "area": "comprehension" } ]
}

{ "standard": { … }, "unit": { "unitId": "…", "name": "…", "description": "…", "skills": [ … ] }, "competencies": [ … ], "criteria": [ … ] }

{ "success": true, "data": { "country": "MX", "countrySource": "query", "pricingTier": "tier_b", "pricingTierLabel": "Equity — Upper-middle income", "pricingDiscountPercent": 50, "currency": "USD" } }

Connect it

• Claude (claude.ai, Desktop, mobile, Cowork): Customize → Connectors → Add custom connector → paste the endpoint, authentication “none”. On Team and Enterprise plans an Owner adds it once for the organisation.
• ChatGPT: Settings → Connectors → Create (developer mode) → paste the endpoint, no authentication.
• Claude Code, Gemini CLI, the Claude API and any other MCP client: snippets below. Listings in the Claude Connectors Directory and the ChatGPT plugin directory are being prepared; until they are live the custom-connector route above is the way in.
• Teachers: the non-technical walkthrough with example prompts is the announcement article Samio for Schools now works inside Claude and ChatGPT.

# Claude Code
claude mcp add --transport http samio https://mcp.samiolearning.com/mcp

# Gemini CLI — ~/.gemini/settings.json
{ "mcpServers": { "samio": { "httpUrl": "https://mcp.samiolearning.com/mcp", "oauth": { "enabled": true } } } }

# Any MCP client / plain HTTP: list the tools (JSON-RPC over Streamable HTTP)
curl -s https://mcp.samiolearning.com/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Claude API — let the model call the server directly (MCP connector, beta)
POST https://api.anthropic.com/v1/messages
anthropic-beta: mcp-client-2025-11-20
{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "mcp_servers": [ { "type": "url", "url": "https://mcp.samiolearning.com/mcp", "name": "samio" } ],
  "tools": [ { "type": "mcp_toolset", "mcp_server_name": "samio" } ],
  "messages": [ { "role": "user", "content": "What does the Dutch curriculum expect in maths for a 7-year-old?" } ]
}

{ "user": { "id": "…", "name": "Ana Ruiz", "email": "ana@school.example", "role": "teacher" },
  "school": { "id": "…", "name": "Colegio Sol", "country": "ES", "language": "es", "plan": "school" },
  "scopes": ["openid", "email", "classes:read", "materials:write"], "app": { "name": "Claude" } }

{ "classes": [ { "classId": "…", "name": "3º A", "gradeLevel": 3, "gradeName": "3.º de Primaria", "subjects": ["math", "reading", …], "language": "es", "studentCount": 24, "academicCalendarId": "…" } ] }

{ "types": [ { "type": "mindmap", "title": "Mind map", "description": "…" }, { "type": "presentation", … }, { "type": "didactic_material", … }, { "type": "study_cards", … } ] }

{ "materialId": "…", "status": "generating", "title": "Fractions — mind map", "materialType": "mindmap", "provenance": "Created with Samio's AI assistant via Claude" }

{ "materialId": "…", "status": "ready", "title": "…", "materialType": "presentation", "subject": "science", "classId": "…", "content": { … }, "provenance": "…", "dashboardUrl": "https://samiolearning.com/schools/dashboard/teaching-materials" }

{ "materials": [ { "materialId": "…", "status": "ready", "title": "…", "materialType": "study_cards", "createdAt": "2026-09-21T09:12:00Z" } ] }

{ "planId": "…", "status": "generating", "mode": "plan", "title": "Matemáticas 3º A 2026–2027", "provenance": "…" }

{ "planId": "…", "status": "active", "mode": "plan", "title": "…", "subject": "math", "classId": "…", "totalWeeks": 36,
  "progress": { "phase": "weeks", "percent": 100, "message": "Done" },
  "weeks": [ { "weekNumber": 1, "title": "Numbers to 1000", "topics": ["Place value", "Comparing"], "status": "pending", "hasLesson": true, "materialIds": [], "challengeIds": [] } ],
  "dashboardUrl": "https://samiolearning.com/schools/dashboard/topic-planner?view=detail&planId=…" }

{ "planId": "…", "weekNumber": 3, "title": "…", "topics": [ … ], "objectives": [ … ], "lesson": { … } | null,
  "materials": [ { "materialId": "…", "title": "…", "materialType": "mindmap", "status": "ready" } ],
  "challenges": [ { "challengeId": "…", "title": "…", "status": "draft" } ] }

{ "plans": [ { "planId": "…", "status": "active", "title": "…", "subject": "reading", "classId": "…", "totalWeeks": 36, "createdAt": "…" } ] }

{ "challengeId": "…", "status": "generating", "title": "Fractions — quiz", "exerciseCount": 0, "preview": [],
  "publishOnReady": false, "dashboardUrl": "https://samiolearning.com/schools/dashboard/challenges?review=…", "provenance": "…" }

{ "challengeId": "…", "status": "draft", "title": "Fractions — quiz", "subject": "math", "classId": "…", "exerciseCount": 5,
  "preview": [ { "type": "fractions", "question": "Which fraction is larger: 2/3 or 3/5?" }, … ],
  "dashboardUrl": "https://samiolearning.com/schools/dashboard/challenges?review=…" }

{ "facts": [ { "factId": "…", "statement": "Photosynthesis converts light energy into chemical energy.", "subject": "science", "topic": "photosynthesis", "language": "en", "sources": [ { "title": "…", "url": "…" } ], "verified": true } ] }

{ "classId": "…", "subject": "math", "standard": { "standardId": "…", "officialName": "…", "gradeName": "…" },
  "coverage": { "percent": 42, "unitsMastered": 5, "unitsInProgress": 3, "unitsPending": 4 },
  "units": [ { "unitId": "…", "name": "Fractions", "status": "in_progress", "percent": 61 } ] }

# Authorization server (RFC 8414; the same document is also served OIDC-shaped for ChatGPT)
GET https://api.samiolearning.com/oauth/.well-known/oauth-authorization-server
GET https://api.samiolearning.com/.well-known/oauth-authorization-server/oauth
GET https://api.samiolearning.com/oauth/.well-known/openid-configuration
GET https://api.samiolearning.com/oauth/jwks.json

# Protected resource (RFC 9728) — what the 401 from /mcp points at
GET https://mcp.samiolearning.com/.well-known/oauth-protected-resource
→ { "resource": "https://mcp.samiolearning.com/mcp",
    "authorization_servers": ["https://api.samiolearning.com/oauth"],
    "scopes_supported": ["openid", "email", "classes:read", "materials:write", "plans:write", "challenges:write", "knowledge:read", "analytics:read"],
    "bearer_methods_supported": ["header"],
    "resource_documentation": "https://samiolearning.com/developers#mcp" }

Prefer plain REST? The agent gateway

Every tool is a thin wrapper over one endpoint of the Samio API’s agent gateway. Developers who would rather call HTTP than MCP can use the curriculum endpoints directly with an app key sent asX-Samio-Agent-Key(request one at info@samiolearning.com). The OpenAPI 3.1 description is public.

GET https://api.samiolearning.com/v1/agent/openapi.json                  # public, no key
GET https://api.samiolearning.com/v1/agent/curriculum/countries
GET https://api.samiolearning.com/v1/agent/curriculum/standards?country=NL&subject=math&age=7&query=optellen
GET https://api.samiolearning.com/v1/agent/curriculum/units/{unitId}?standardId={standardId}
GET https://api.samiolearning.com/v1/agent/pricing?country=MX

# errors are { "error": "...", "code": "..." }
# 400 INVALID_COUNTRY | INVALID_SUBJECT | INVALID_GRADE | INVALID_AGE | INVALID_LANGUAGE | INVALID_QUERY | INVALID_LIMIT
# 401 AGENT_KEY_INVALID · 403 AGENT_APP_DISABLED · 404 NO_CURRICULUM | UNIT_NOT_FOUND
# 429 AGENT_QUOTA_EXCEEDED (+ Retry-After) · 503 AGENT_ACCESS_DISABLED

# Teacher endpoints (Tier B) take BOTH the app key and the teacher's OAuth bearer:
GET  https://api.samiolearning.com/v1/agent/me
GET  https://api.samiolearning.com/v1/agent/classes
POST https://api.samiolearning.com/v1/agent/teaching-materials          # 202 { materialId, status: "generating" }
GET  https://api.samiolearning.com/v1/agent/teaching-materials/{materialId}
POST https://api.samiolearning.com/v1/agent/topic-plans                 # 202 { planId, status: "generating" }
GET  https://api.samiolearning.com/v1/agent/topic-plans/{planId}
GET  https://api.samiolearning.com/v1/agent/topic-plans/{planId}/weeks/{n}
POST https://api.samiolearning.com/v1/agent/challenges
GET  https://api.samiolearning.com/v1/agent/knowledge/facts?subject=&topic=
GET  https://api.samiolearning.com/v1/agent/classes/{classId}/curriculum-progress?subject=
# 401 AGENT_TOKEN_INVALID · 403 AGENT_SCOPE_MISSING | AGENT_GRANT_REVOKED · 402 PLAN_LIMIT_REACHED
# 404 CLASS_NOT_FOUND | PLAN_NOT_FOUND | MATERIAL_NOT_FOUND | WEEK_NOT_FOUND · 409 GENERATION_IN_PROGRESS
# 429 AGENT_SCHOOL_QUOTA_EXCEEDED (+ Retry-After)

• Quotas: 600 calls per hour per app key and 120 per hour per client IP for developer apps; the MCP endpoint itself allows 120 requests per hour per IP. Curriculum responses carry Cache-Control: public, max-age=3600.
• Audit: one row per call with the route template, status, duration, a hash of the inputs and a salted hash of the IP; no free text, no personal data, purged after 180 days.
• The tool names and input schemas are identical on the MCP server and in the gateway’s OpenAPI file, so a client can switch between the two without remapping.

Problems, feature requests or a developer key: info@samiolearning.com. The gateway can be switched off centrally; when it is, every call answers 503 AGENT_ACCESS_DISABLED.