@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Data API
@base https://api.clever.com/v1.2
@version 1.2.0
@auth OAuth2
@endpoints 44
@hint download_for_search
@toc contacts(4), district_admins(2), districts(8), school_admins(3), schools(6), sections(7), students(7), teachers(7)

@group contacts
@endpoint GET /contacts
@desc Returns a list of student contacts
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response

@endpoint GET /contacts/{id}
@desc Returns a specific student contact
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /contacts/{id}/district
@desc Returns the district for a student contact
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /contacts/{id}/student
@desc Returns the student for a student contact
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group district_admins
@endpoint GET /district_admins
@desc Returns a list of district admins
@optional {starting_after: any, ending_before: any, show_links: any}
@returns(200) OK Response

@endpoint GET /district_admins/{id}
@desc Returns a specific district admin
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group districts
@endpoint GET /districts
@desc Returns a list of districts. In practice this will only return the one district associated with the bearer token
@returns(200) OK Response

@endpoint GET /districts/{id}
@desc Returns a specific district
@required {id: any}
@optional {include: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/admins
@desc Returns the admins for a district
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/schools
@desc Returns the schools for a district
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/sections
@desc Returns the sections for a district
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/status
@desc Returns the status of the district
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/students
@desc Returns the students for a district
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /districts/{id}/teachers
@desc Returns the teachers for a district
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group school_admins
@endpoint GET /school_admins
@desc Returns a list of school admins
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response

@endpoint GET /school_admins/{id}
@desc Returns a specific school admin
@required {id: any}
@optional {include: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /school_admins/{id}/schools
@desc Returns the schools for a school admin
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group schools
@endpoint GET /schools
@desc Returns a list of schools
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response

@endpoint GET /schools/{id}
@desc Returns a specific school
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /schools/{id}/district
@desc Returns the district for a school
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /schools/{id}/sections
@desc Returns the sections for a school
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /schools/{id}/students
@desc Returns the students for a school
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /schools/{id}/teachers
@desc Returns the teachers for a school
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group sections
@endpoint GET /sections
@desc Returns a list of sections
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response

@endpoint GET /sections/{id}
@desc Returns a specific section
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /sections/{id}/district
@desc Returns the district for a section
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /sections/{id}/school
@desc Returns the school for a section
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /sections/{id}/students
@desc Returns the students for a section
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /sections/{id}/teacher
@desc Returns the primary teacher for a section
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /sections/{id}/teachers
@desc Returns the teachers for a section
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group students
@endpoint GET /students
@desc Returns a list of students
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response

@endpoint GET /students/{id}
@desc Returns a specific student
@required {id: any}
@optional {include: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /students/{id}/contacts
@desc Returns the contacts for a student
@required {id: any}
@optional {limit: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /students/{id}/district
@desc Returns the district for a student
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /students/{id}/school
@desc Returns the primary school for a student
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /students/{id}/sections
@desc Returns the sections for a student
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /students/{id}/teachers
@desc Returns the teachers for a student
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@group teachers
@endpoint GET /teachers
@desc Returns a list of teachers
@optional {limit: any, starting_after: any, ending_before: any, where: any}
@returns(200) OK Response

@endpoint GET /teachers/{id}
@desc Returns a specific teacher
@required {id: any}
@optional {include: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /teachers/{id}/district
@desc Returns the district for a teacher
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /teachers/{id}/grade_levels
@desc Returns the grade levels for sections a teacher teaches
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /teachers/{id}/school
@desc Retrieves school info for a teacher.
@required {id: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /teachers/{id}/sections
@desc Returns the sections for a teacher
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endpoint GET /teachers/{id}/students
@desc Returns the students for a teacher
@required {id: any}
@optional {limit: any, starting_after: any, ending_before: any}
@returns(200) OK Response
@errors {404: Entity Not Found}

@endgroup

@end