Riferimento API Edu-V

Panoramica

Samio partecipa a Edu-V (release NR26) come dashboard di progresso per gli insegnanti. È afnemer (consumatore) di dati di amministrazione scolastica — onderwijsinrichting, onderwijsdeelnemers, onderwijsmedewerkers e gruppi — dai SIS olandesi come ParnasSys ed ESIS, e verzender (mittente) dei risultati di apprendimento prodotti nell'app gratuita per alunni di Samio. Samio non è un portale: non riceve diritti, dati di catalogo né risultati.

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

Autenticazione

Tutti gli endpoint richiedono un token Bearer ottenuto tramite OAuth 2.0 con il profilo NL GOV (autenticazione 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"
}

Codici di errore

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

Paginazione

Gli endpoint paginati accettano i parametri start e limit.

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

Scopes

Scopes OAuth 2.0 disponibili per l'integrazione Edu-V.

Modelli dati

Avvio rapido

Flusso di integrazione completo dalla registrazione del partner alla lettura dei risultati.

Strumenti per agenti (WebMCP)

Strumenti che gli agenti IA nel browser possono richiamare su samiolearning.com: quattro di sola lettura su ogni pagina pubblica (prezzi per paese, ricerca pagine, dati di prodotto, link delle app) e, per un insegnante autenticato nella dashboard scolastica, gli stessi dodici strumenti per insegnanti del server MCP, eseguiti con la sessione dell'insegnante.

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.

Server MCP remoto (Samio per le Scuole)

Un server MCP remoto a cui può collegarsi qualsiasi assistente IA — Claude, ChatGPT, Gemini, Claude Code o il tuo agente. Quattro strumenti di sola lettura sui curricoli ufficiali della scuola primaria in oltre 60 paesi e i prezzi di Samio per le Scuole funzionano senza login; tredici strumenti per insegnanti (materiali, piani tematici, sfide, fatti verificati, copertura per classe) si attivano quando un insegnante collega il proprio account Samio per le Scuole con OAuth 2.1. Nessun dato degli alunni, in nessuno strumento.

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.