Référence API Edu-V

Aperçu

Samio participe à Edu-V (version NR26) comme tableau de bord de progression pour les enseignants. Samio est afnemer (consommateur) des données d'administration scolaire — onderwijsinrichting, onderwijsdeelnemers, onderwijsmedewerkers et groupes — issues des SIS néerlandais tels que ParnasSys et ESIS, et verzender (émetteur) des résultats produits dans l'app élève gratuite de Samio. Samio n'est pas un portail : il ne reçoit ni droits d'accès, ni catalogue, ni résultats.

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
├── GET  {sis}/education|students|employees|groups   # afnemer
└── POST {receiver}/results                          # verzender

Authentification

Tous les endpoints nécessitent un token Bearer obtenu via OAuth 2.0 avec le profil NL GOV (authentification client private_key_jwt).

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.read eduv.association"

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

Codes d'erreur

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

Pagination

Les endpoints paginés acceptent les paramètres start et limit.

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

Scopes

Scopes OAuth 2.0 disponibles pour l'intégration Edu-V.

Modèles de données

Démarrage rapide

Flux d'intégration complet de l'enregistrement du partenaire à la lecture des résultats.

Outils pour agents (WebMCP)

Outils que les agents IA du navigateur peuvent appeler sur samiolearning.com : quatre outils en lecture seule sur chaque page publique (prix par pays, recherche de pages, fiches produit, liens d'apps) et, pour un enseignant connecté au tableau de bord, les douze mêmes outils enseignants que le serveur MCP — exécutés avec la session de l'enseignant.

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.

Serveur MCP distant (Samio pour les écoles)

Un serveur MCP distant auquel tout assistant IA peut se connecter — Claude, ChatGPT, Gemini, Claude Code ou votre propre agent. Quatre outils en lecture seule sur les programmes officiels du primaire dans plus de 60 pays et les tarifs de Samio pour les écoles fonctionnent sans connexion ; treize outils enseignants (supports, plans thématiques, défis, faits vérifiés, couverture par classe) s'activent lorsqu'un enseignant relie son compte Samio pour les écoles via OAuth 2.1. Aucune donnée d'élève, sur aucun outil.

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 (60+ countries, 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?challenge=…", "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?challenge=…" }

{ "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.