GET /ed-fi/[DescriptorName]Descriptors (e.g., /ed-fi/gradeLevelDescriptors) to retrieve the full list of descriptors currently defined on the target ODS instance.
Identify which descriptors use the ed-fi.org namespace versus a state or local namespace; only post local codes into your own namespace (e.g., uri://yourdistrict.edu/AcademicSubjectDescriptor#Linear Algebra II).
POST a new descriptor to /ed-fi/[descriptorName]Descriptors with body containing namespace, codeValue, shortDescription, and description when a local value has no matching ed-fi.org equivalent.
In Ed-Fi Data Standard v4+, use the descriptorMappings resource to record the formal mapping between your local descriptor URI and the corresponding state or ed-fi.org descriptor URI, enabling downstream consumers to translate values.
Store the returned descriptor URI strings in your local mapping table keyed by your SIS's internal code so every subsequent API write resolves the correct descriptor URI without repeated lookups.
When migrating between ODS versions, re-fetch all descriptor lists and re-validate your mapping table since descriptor codeValues and namespaces can change across Data Standard versions.
Known gotchas
Never write local codes into the uri://ed-fi.org/ namespace; that namespace is reserved for standard descriptors and the API may reject or silently corrupt such entries.
Descriptor URIs are case-sensitive; a mismatch in capitalization between what your mapping table stores and what the ODS expects will cause a 400 validation error on write.
Descriptor lists vary by ODS deployment — a descriptor valid on one state's ODS may not exist on another's, so always fetch and validate against the target instance rather than assuming a universal set.
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