Register your application in the Ed-Fi ODS admin UI to obtain a client key and secret, then POST to /oauth/token with grant_type=client_credentials to receive a Bearer token.
Resolve dependency order: POST /ed-fi/students first to create the student record, then POST /ed-fi/studentSchoolAssociations to establish the school enrollment with required fields schoolId, studentUniqueId, entryDate, and entryGradeLevelDescriptor.
POST /ed-fi/studentSectionAssociations to enroll the student in specific sections, referencing the sectionReference (schoolId, localCourseCode, schoolYear, sectionIdentifier, sessionName) and studentReference.
For updates, use PUT to the resource URI returned in the Location header of the original POST; include the full resource body as the API does not support PATCH by default.
Poll GET /ed-fi/studentSchoolAssociations?limit=500&offset=0 with pagination to verify sync state; compare changeVersion values using the /changeQueries/v1/studentSchoolAssociations endpoint to detect incremental changes.
Handle 409 Conflict responses (duplicate natural key) by switching to PUT; handle 400 responses by checking the descriptor URI format, which must follow uri://[namespace]/[DescriptorName]#[value].
Known gotchas
Resources must be posted in dependency order: Student before StudentSchoolAssociation before StudentSectionAssociation; posting out of order returns a 409 or 400 referencing an unresolved reference.
Descriptor values are URIs such as uri://ed-fi.org/EntryGradeLevelDescriptor#Ninth grade — sending a plain string like 'Ninth grade' causes a validation error.
The Change Queries API (used for delta sync) must be explicitly enabled on the ODS instance; it is not on by default in all deployments.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp