Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Academics

This group refers to top-level entities such as School, Programs, Subjects, and Academic Years. Programs are curriculum frameworks that ManageBac supports, and a Subject is a collection of delivered curricula. Academic Years define when the school is in session.

Upload a OneRoster Bundle

post
/v2/one-roster/imports

Submit a zip archive file for ManageBac to process as an import. The import mode is determined by the manifest.

The bundle is queued rather than processed inline: a 202 means ManageBac has taken responsibility for it and identifies the import that was created. Validation results and the outcome appear under Data Exchange history in ManageBac, where the run is listed as generated by API Caller.

The import is always created for the school owning the API credential.

Please note that source.systemCode defines a namespace that scopes sourcedId mappings from previous imports. These sourcedIds can be matched against on import. A bundle that declares no source.systemCode imports into the unnamed namespace, which it shares with every other bundle that declares none.

Only one OneRoster exchange runs per school at a time. While an import or export is already in flight this endpoint returns 409 instead of holding the bundle, so a caller can retry once the running exchange has finished. That response names the import in the way as import_id; when an export is what blocks the upload there is no import to name and the field is absent. An exchange that has not progressed for over an hour is treated as abandoned and stops blocking further uploads.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Body
filestring · binaryRequired
Responses
202

Accepted

application/json
post/v2/one-roster/imports
POST /v2/one-roster/imports HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}
{
  "import": {
    "id": 10001,
    "status": "scheduled",
    "processing_mode": "bulk",
    "system_name": "DataGen",
    "system_code": "DataGen",
    "dry_run": false,
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}

Create Academic Term

post
/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms

Creates an Academic Term within the specified Academic Year.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: diploma
academic_year_idstringRequired

Academic Year ID

Example: 123
Body
Responses
200

Success

application/json
post/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms
POST /v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "academic_term": {
    "name": "Term one.",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "locked": true,
    "enable_exam_grade": false
  }
}
{
  "academic_term": {
    "id": 123,
    "academic_year_id": 124,
    "name": "Term 1",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "locked": true,
    "exam_grade": true,
    "updated_at": "2023-06-26T08:54:47.000Z"
  }
}

Delete Academic Term

delete
/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id}

Deletes an Academic Term from the specified Academic Year by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: diploma
academic_year_idintegerRequired

Academic Year ID

Example: 123
idintegerRequired

Academic Term ID

Example: 123
Responses
200

Success

application/json
delete/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id}
DELETE /v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "academic_term": {
    "id": 123,
    "academic_year_id": 124,
    "name": "Term 1",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "locked": true,
    "exam_grade": true,
    "updated_at": "2023-06-26T08:54:47.000Z"
  }
}

Update Academic Term

patch
/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id}

Updates an Academic Term within the specified Academic Year by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: diploma
academic_year_idstringRequired

Academic Year ID

Example: 123
idstringRequired

Academic Term ID

Example: 123
Body
Responses
200

Success

application/json
patch/v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id}
PATCH /v2/school/programs/{program_code}/academic-years/{academic_year_id}/academic-terms/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "academic_term": {
    "name": "Term one.",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "locked": true,
    "enable_exam_grade": false
  }
}
{
  "academic_term": {
    "id": 123,
    "academic_year_id": 124,
    "name": "Term 1",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "locked": true,
    "exam_grade": true,
    "updated_at": "2023-06-26T08:54:47.000Z"
  }
}

Retrieve Academic Year

get
/v2/school/programs/{program_code}/academic-years/{id}

Retrieves an Academic Year by ID, including its associated Academic Terms.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program code

Example: diploma
idintegerRequired

Unique ID in ManageBac.

Example: 10010
Responses
200

Success

application/json
get/v2/school/programs/{program_code}/academic-years/{id}
GET /v2/school/programs/{program_code}/academic-years/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "academic_year": {
    "id": 123,
    "name": "August 2023 – January 2024",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "updated_at": "2023-06-26T08:54:47.000Z",
    "program": "diploma",
    "academic_terms": [
      {
        "id": 123,
        "academic_year_id": 124,
        "name": "Term 1",
        "starts_on": "2024-05-29",
        "ends_on": "2024-07-29",
        "locked": true,
        "exam_grade": true,
        "updated_at": "2023-06-26T08:54:47.000Z"
      }
    ]
  }
}

Create Academic Year

post
/v2/school/programs/{program_code}/academic-years

Creates an Academic Year with its associated Academic Terms.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program code

Example: diploma
Body
Responses
200

Success

application/json
post/v2/school/programs/{program_code}/academic-years
POST /v2/school/programs/{program_code}/academic-years HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "academic_year": {
    "terms_attributes": [
      {
        "name": "Term one.",
        "starts_on": "2024-05-29",
        "ends_on": "2024-07-29",
        "locked": true,
        "enable_exam_grade": false
      }
    ]
  }
}
{
  "academic_year": {
    "id": 123,
    "name": "August 2023 – January 2024",
    "starts_on": "2024-05-29",
    "ends_on": "2024-07-29",
    "updated_at": "2023-06-26T08:54:47.000Z",
    "program": "diploma",
    "academic_terms": [
      {
        "id": 123,
        "academic_year_id": 124,
        "name": "Term 1",
        "starts_on": "2024-05-29",
        "ends_on": "2024-07-29",
        "locked": true,
        "exam_grade": true,
        "updated_at": "2023-06-26T08:54:47.000Z"
      }
    ]
  }
}

Retrieves Assessment Types

get
/v2/school/programs/{program_code}/assessment_types

Retrieves the list of assessment types configured for a given program. Each assessment type includes its kind (e.g. summative, formative), display name, color code, and the assessment methods that are available or required for that type (binary, criteria, comment, points).

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

The short code identifying the program (e.g. "ibpyp", "diploma", "igcse").

Example: ibpyp
Responses
200

Success

application/json
get/v2/school/programs/{program_code}/assessment_types
GET /v2/school/programs/{program_code}/assessment_types HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "assessment_type": {
    "id": 3,
    "kind": "summative",
    "name": "Summative",
    "color_code": "#478cfe",
    "available_assessments": [
      "binary"
    ],
    "required_assessments": [
      "criteria"
    ]
  }
}

Get Academic Year Calendar

get
/v2/school/programs/{program_code}/academic-years/{academic_year_id}/calendar

Retrieves the academic year calendar for a specific program and academic year. Returns the calendar configuration (type, rotation cycle length, days off, whether holidays are ignored) and an array of dates with their assigned rotation day numbers. Vacation days are excluded from the rotation sequence.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

The short code identifying the program (e.g. "diploma", "ibpyp").

Example: diploma
academic_year_idintegerRequired

The unique numeric identifier of the academic year.

Example: 10010
Responses
200

Success

application/json
get/v2/school/programs/{program_code}/academic-years/{academic_year_id}/calendar
GET /v2/school/programs/{program_code}/academic-years/{academic_year_id}/calendar HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "calendar": {
    "start_date": "2024-06-17",
    "end_date": "2025-06-15",
    "calendar_type": "Rotation Cycle",
    "rotation_cycle": 5,
    "ignore_holidays": true,
    "days_off": [
      0,
      6
    ],
    "dates": [
      {
        "date": "2024-06-17",
        "rotation_day": 1
      },
      {
        "date": "2024-06-18",
        "rotation_day": 2
      },
      {
        "date": "2024-06-19",
        "rotation_day": 3
      },
      {
        "date": "2024-06-24",
        "rotation_day": 5
      }
    ]
  }
}

Get All Term Reports

get
/v2/school/programs/{program}/reports

Retrieves a list of published term reports for the specified program. Each report includes download URLs for PDF, individual reports ZIP, and term grades ZIP when available. Only non-draft reports are returned.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
programstringRequired

Program code (e.g. diploma, myp, pyp, cp)

Example: diploma
Query parameters
academic_term_idintegerOptional

Filter by academic term ID

typestringOptional

Filter by report type: final or interim:

  • final
  • interim
Responses
200

Success

application/json
get/v2/school/programs/{program}/reports
GET /v2/school/programs/{program}/reports HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "term_reports": [
    {
      "id": 1,
      "title": "text",
      "type": "final",
      "program": "text",
      "academic_term_id": 1,
      "academic_term_name": "text",
      "next_gen": true,
      "pdf_url": "text",
      "individual_reports_url": "text",
      "term_grades_url": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "released_on": "2026-01-01"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 1
  }
}

Get Term Report

get
/v2/school/programs/{program}/reports/{id}

Retrieves a single published term report by ID, with download URLs for available files.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
programstringRequired

Program code

Example: diploma
idintegerRequired

Term report ID

Responses
200

Success

application/json
get/v2/school/programs/{program}/reports/{id}
GET /v2/school/programs/{program}/reports/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "term_report": {
    "id": 1,
    "title": "text",
    "type": "final",
    "program": "text",
    "academic_term_id": 1,
    "academic_term_name": "text",
    "next_gen": true,
    "pdf_url": "text",
    "individual_reports_url": "text",
    "term_grades_url": "text",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "released_on": "2026-01-01"
  }
}

Download Term Report File

get
/v2/school/programs/{program}/reports/{id}/download/{kind}

Returns a 302 redirect to a pre-signed download URL for the requested file. Supported file types: pdf (master PDF), individual_reports (ZIP of individual student PDFs), term_grades (ZIP of term grades export).

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
programstringRequired

Program code (e.g. diploma, myp, pyp, cp)

Example: diploma
idintegerRequired

Term report ID

kindstringRequired

File type to download:

  • pdf
  • individual_reports
  • term_grades
Responses
302

Redirect to download URL

No content
get/v2/school/programs/{program}/reports/{id}/download/{kind}
GET /v2/school/programs/{program}/reports/{id}/download/{kind} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieves Subject Groups

get
/v2/school/programs/{program_code}/subject-groups

Retrieves a paginated list of Subject Groups for the specified program.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: ibpyp
Query parameters
pagestringOptional

An integer defining which page to display.

per_pagestringOptional

An integer defining the number of records to display per page.

modified_sincestringOptional

A timestamp to filter the modification date of results.

Responses
200

Success

application/json
get/v2/school/programs/{program_code}/subject-groups
GET /v2/school/programs/{program_code}/subject-groups HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 20,
    "per_page": 2
  },
  "subject_groups": [
    {
      "id": 10010,
      "name": "Language",
      "max_phase": "4",
      "program": "ibpyp",
      "updated_at": "2021-05-13T10:27:47Z"
    }
  ]
}

Create Subject Group

post
/v2/school/programs/{program_code}/subject-groups

Creates a new Subject Group for the specified program.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: hs
Body
Responses
200

Success

application/json
post/v2/school/programs/{program_code}/subject-groups
POST /v2/school/programs/{program_code}/subject-groups HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "subject_group": {
    "name": "Language",
    "max_phase": "4"
  }
}
{
  "subject_group": {
    "id": 10010,
    "name": "Language",
    "custom": true,
    "max_phase": "4",
    "program": "ibpyp",
    "updated_at": "2021-05-13T10:27:47Z"
  }
}

Get Subject Group

get
/v2/school/programs/{program_code}/subject-groups/{id}

Retrieves a single Subject Group by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: hs
idintegerRequired

Unique ID for Subject Group in ManageBac.

Example: 10001
Responses
200

Success

application/json
get/v2/school/programs/{program_code}/subject-groups/{id}
GET /v2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subject_group": {
    "id": 10010,
    "name": "Language",
    "custom": true,
    "max_phase": "4",
    "program": "ibpyp",
    "updated_at": "2021-05-13T10:27:47Z"
  }
}

Remove Subject Group

delete
/v2/school/programs/{program_code}/subject-groups/{id}

Deletes a Subject Group by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: hs
idintegerRequired

Subject Group ID

Example: 10010
Responses
200

Success

application/json
delete/v2/school/programs/{program_code}/subject-groups/{id}
DELETE /v2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subject_group": {
    "id": 10010,
    "name": "Language",
    "custom": true,
    "max_phase": "4",
    "program": "ibpyp",
    "updated_at": "2021-05-13T10:27:47Z"
  }
}

Update Subject Group

patch
/v2/school/programs/{program_code}/subject-groups/{id}

Updates an existing Subject Group by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: hs
idintegerRequired

Subject Group ID

Example: 10010
Body
Responses
200

Success

application/json
patch/v2/school/programs/{program_code}/subject-groups/{id}
PATCH /v2/school/programs/{program_code}/subject-groups/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "subject_group": {
    "name": "Language",
    "max_phase": "4"
  }
}
{
  "subject_group": {
    "id": 10010,
    "name": "Language",
    "custom": true,
    "max_phase": "4",
    "program": "ibpyp",
    "updated_at": "2021-05-13T10:27:47Z"
  }
}

Retrieves Subjects

get
/v2/school/programs/{program_code}/subjects

Retrieves a paginated list of Subjects for the specified program.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: ibpyp
Query parameters
pagestringOptional

An integer defining which page to display.

per_pagestringOptional

An integer defining the number of records to display per page.

Responses
200

Success

application/json
get/v2/school/programs/{program_code}/subjects
GET /v2/school/programs/{program_code}/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 20,
    "per_page": 2
  },
  "subjects": [
    {
      "id": 10001,
      "subject_group_id": 10001,
      "custom": false,
      "name": "English",
      "title": "English",
      "sl": false,
      "hl": true,
      "sl_code": 138,
      "hl_code": 128,
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "scope_and_sequence_based_on": "phases",
      "updated_at": "2021-05-13T10:27:47Z",
      "self_taught": true,
      "phases": [
        "1",
        "2",
        "3",
        "4"
      ],
      "levels": [
        "Literature",
        "Language and literature"
      ],
      "enabled": true
    }
  ]
}

Creates Subject

post
/v2/school/programs/{program_code}/subjects

Creates a new Subject for the specified program.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: hs
Body
Responses
200

Success

application/json
post/v2/school/programs/{program_code}/subjects
POST /v2/school/programs/{program_code}/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302

{
  "subject": {
    "subject_group_id": 10001,
    "name": "English",
    "title": "English",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "sl": false,
    "hl": true,
    "enabled": true,
    "code": "X128"
  }
}
{
  "subject": {
    "id": 10001,
    "subject_group_id": 10001,
    "custom": true,
    "name": "English",
    "title": "English",
    "sl": false,
    "hl": true,
    "code": "X128",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "updated_at": "2021-05-13T10:27:47Z",
    "self_taught": true,
    "phases": [
      "1",
      "2",
      "3",
      "4"
    ],
    "levels": [
      "Literature",
      "Language and literature"
    ],
    "enabled": true
  }
}

Retrieves Subject

get
/v2/school/programs/{program_code}/subjects/{id}

Retrieves a single Subject by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: ibpyp
idintegerRequired

Unique ID for Subject in ManageBac.

Example: 10001
Responses
200

Success

application/json
get/v2/school/programs/{program_code}/subjects/{id}
GET /v2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subject": {
    "id": 10001,
    "subject_group_id": 10001,
    "custom": true,
    "name": "English",
    "title": "English",
    "sl": false,
    "hl": true,
    "code": "X128",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "updated_at": "2021-05-13T10:27:47Z",
    "self_taught": true,
    "phases": [
      "1",
      "2",
      "3",
      "4"
    ],
    "levels": [
      "Literature",
      "Language and literature"
    ],
    "enabled": true
  }
}

Updates Subject

put
/v2/school/programs/{program_code}/subjects/{id}

Updates an existing Subject by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: ibpyp
idintegerRequired

Unique ID for Subject in ManageBac.

Example: 10001
Body
Responses
200

Success

application/json
put/v2/school/programs/{program_code}/subjects/{id}
PUT /v2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302

{
  "subject": {
    "subject_group_id": 10001,
    "name": "English",
    "title": "English",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "sl": false,
    "hl": true,
    "enabled": true,
    "code": "X128"
  }
}
{
  "subject": {
    "id": 10001,
    "subject_group_id": 10001,
    "custom": true,
    "name": "English",
    "title": "English",
    "sl": false,
    "hl": true,
    "code": "X128",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "updated_at": "2021-05-13T10:27:47Z",
    "self_taught": true,
    "phases": [
      "1",
      "2",
      "3",
      "4"
    ],
    "levels": [
      "Literature",
      "Language and literature"
    ],
    "enabled": true
  }
}

Delete Subject

delete
/v2/school/programs/{program_code}/subjects/{id}

Deletes a Subject by ID.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Path parameters
program_codestringRequired

Program scope

Example: ibpyp
idintegerRequired

Unique ID for Subject in ManageBac.

Example: 10001
Responses
200

Success

application/json
delete/v2/school/programs/{program_code}/subjects/{id}
DELETE /v2/school/programs/{program_code}/subjects/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subject": {
    "id": 10001,
    "subject_group_id": 10001,
    "custom": true,
    "name": "English",
    "title": "English",
    "sl": false,
    "hl": true,
    "code": "X128",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "scope_and_sequence_based_on": "phases",
    "updated_at": "2021-05-13T10:27:47Z",
    "self_taught": true,
    "phases": [
      "1",
      "2",
      "3",
      "4"
    ],
    "levels": [
      "Literature",
      "Language and literature"
    ],
    "enabled": true
  }
}

Get School Details

get
/v2/school

Retrieves the School's basic information including name, country, language, logo URLs, and the list of enabled academic programs (e.g. IB Diploma, MYP, PYP).

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Responses
200

Success

application/json
get/v2/school
GET /v2/school HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "school": {
    "subdomain": "faria",
    "name": "Faria International School",
    "country": "US",
    "language": "en",
    "session_in_may": true,
    "logo": "path/to/logo.png",
    "top_nav_logo": "path/to/top_nav_logo.png",
    "high_res_logo": "path/to/high_res_logo.png",
    "programs": [
      "IB Diploma",
      "IB Middle Years",
      "IB Primary Years",
      "High School",
      "Middle School",
      "Primary School"
    ],
    "enabled_programs": [
      {
        "name": "IB Diploma",
        "code": "diploma"
      },
      {
        "name": "IB Middle Years",
        "code": "myp"
      },
      {
        "name": "IB Primary Years",
        "code": "ibpyp"
      },
      {
        "name": "High School",
        "code": "hs"
      },
      {
        "name": "Middle School",
        "code": "ms"
      },
      {
        "name": "Primary School",
        "code": "ps"
      }
    ],
    "kbl_id": 5
  }
}

Get Academic Years

get
/v2/school/academic-years

Retrieves academic years and their terms for each enabled program at the School. Results are grouped by program code (e.g. diploma, myp, ibpyp). Each academic year includes its terms with start/end dates and active status.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Query parameters
program_codestringOptional

Filter by program code (e.g. 'diploma', 'myp', 'hs'). Omit to return all programs.

activebooleanOptional

Filter by active status. When true, returns only currently active academic years.

Responses
200

Success

application/json
get/v2/school/academic-years
GET /v2/school/academic-years HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "academic_years": {
    "diploma": {
      "academic_years": [
        {
          "id": 26278,
          "name": "August 2018 – July 2019",
          "active": true,
          "starts_on": "2018-08-15",
          "ends_on": "2019-07-30",
          "updated_at": "2017-12-21T16:50:47.000+08:00",
          "academic_terms": [
            {
              "id": 62755,
              "name": "Term 1",
              "active": true,
              "starts_on": "2018-08-15",
              "ends_on": "2018-12-31",
              "updated_at": "2018-04-21T16:50:47.000+08:00",
              "exam_grade": false
            },
            {
              "id": 62756,
              "name": "Term 2",
              "active": false,
              "starts_on": "2019-01-03",
              "ends_on": "2019-07-30",
              "updated_at": "2018-04-14T17:37:35.000+08:00",
              "exam_grade": false
            }
          ]
        }
      ]
    },
    "myp": {
      "academic_years": [
        {
          "id": 24648,
          "name": "August 2018 – July 2019",
          "active": true,
          "starts_on": "2018-08-19",
          "ends_on": "2019-07-01",
          "updated_at": "2018-04-09T05:09:12.000+08:00",
          "academic_terms": [
            {
              "id": 58813,
              "name": "Term 1",
              "active": false,
              "starts_on": "2018-08-19",
              "ends_on": "2019-01-29",
              "updated_at": "2018-04-09T05:09:12.000+08:00",
              "exam_grade": false
            },
            {
              "id": 58814,
              "name": "Term 2",
              "active": true,
              "starts_on": "2019-02-01",
              "ends_on": "2019-07-01",
              "updated_at": "2016-04-09T05:09:12.000+08:00",
              "exam_grade": false
            }
          ]
        }
      ]
    },
    "ib_pyp": {
      "academic_years": [
        {
          "id": 31796,
          "name": "August 2018 – June 2019",
          "active": false,
          "starts_on": "2018-08-10",
          "ends_on": "2019-06-03",
          "updated_at": "2018-04-28T23:54:16.000+08:00",
          "academic_terms": [
            {
              "id": 76082,
              "name": "Term One",
              "active": false,
              "starts_on": "2018-08-10",
              "ends_on": "2019-01-01",
              "updated_at": "2018-05-28T23:54:16.000+08:00",
              "exam_grade": false
            },
            {
              "id": 76083,
              "name": "Quarter 1",
              "active": false,
              "starts_on": "2019-01-04",
              "ends_on": "2019-06-03",
              "updated_at": "2018-05-28T23:54:16.000+08:00",
              "exam_grade": false
            }
          ]
        }
      ]
    }
  }
}

Get School Grades

get
/v2/school/grades

Retrieves the grade levels defined for each enabled program at the School. Grades are grouped by program and include the grade name, label, code, UID, and grade number. The label is the school's customized display name for the grade.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Responses
200

Success

application/json
get/v2/school/grades
GET /v2/school/grades HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "school": {
    "programs": [
      {
        "name": "IB Diploma",
        "code": "diploma",
        "grades": [
          {
            "name": "Grade 9",
            "label": "Pre-DP Grade 10",
            "code": "diploma;10",
            "uid": 100120013,
            "grade_number": 10
          },
          {
            "name": "Grade 10",
            "label": "Pre-DP Grade 11",
            "code": "diploma;11",
            "uid": 100120014,
            "grade_number": 11
          }
        ]
      },
      {
        "name": "IB Middle Years",
        "code": "myp",
        "grades": [
          {
            "name": "Year 1",
            "label": "Grade 6",
            "code": "myp;7",
            "uid": 100110010,
            "grade_number": 7
          },
          {
            "name": "Year 2",
            "label": "Grade 7",
            "code": "myp;8",
            "uid": 100110011,
            "grade_number": 8
          }
        ]
      },
      {
        "name": "IB Primary Years",
        "code": "pyp",
        "grades": [
          {
            "name": "Pre-Nursery",
            "label": "Test",
            "code": "pyp;-2",
            "uid": 100100001,
            "grade_number": -2
          },
          {
            "name": "Nursery",
            "label": "Pre-K3",
            "code": "pyp;-1",
            "uid": 100100002,
            "grade_number": -1
          }
        ]
      }
    ]
  }
}

Get School Subjects

get
/v2/school/subjects

Retrieves the subjects available for each enabled program at the School. Subjects are grouped by program code. Each subject includes its name, subject group, and level availability (HL/SL) where applicable. Deprecated subjects are excluded from the response.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Responses
200

Success

application/json
get/v2/school/subjects
GET /v2/school/subjects HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "subjects": {
    "diploma": [
      {
        "id": 1,
        "name": "Mathematical Studies",
        "group": "Mathematics",
        "group_id": 1,
        "hl": true,
        "sl": true
      },
      {
        "id": 16,
        "name": "Chinese",
        "group": "Language acquisition",
        "group_id": 2,
        "hl": true,
        "sl": true,
        "self_taught": false,
        "levels": [
          "B",
          "ab initio"
        ]
      },
      {
        "id": 27,
        "name": "French",
        "group": "Language acquisition",
        "group_id": 3,
        "hl": true,
        "sl": true,
        "self_taught": false,
        "levels": [
          "B",
          "ab initio"
        ]
      }
    ],
    "myp": [
      {
        "id": 348,
        "name": "Physical and health education",
        "group": "Physical and health education",
        "group_id": 4
      },
      {
        "id": 350,
        "name": "Arts",
        "group": "Arts",
        "group_id": 5
      }
    ]
  }
}

Get School Term Grade Scales

get
/v2/school/term-grade-scales

Retrieves the term grade scales defined for each enabled program at the School. Each scale entry maps a percentage score threshold to a mark (e.g. score 95.0 maps to mark "7" for IB Diploma). These scales determine how numerical scores are converted to grade marks on term reports.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Responses
200

Success

application/json
get/v2/school/term-grade-scales
GET /v2/school/term-grade-scales HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "school": {
    "term_grade_scales": [
      {
        "score": 95,
        "mark": "7",
        "program_code": "diploma"
      },
      {
        "score": 80,
        "mark": "6",
        "program_code": "diploma"
      },
      {
        "score": 70,
        "mark": "5",
        "program_code": "diploma"
      },
      {
        "score": 60,
        "mark": "4",
        "program_code": "diploma"
      },
      {
        "score": 50,
        "mark": "3",
        "program_code": "diploma"
      },
      {
        "score": 40,
        "mark": "2",
        "program_code": "diploma"
      },
      {
        "score": 0,
        "mark": "1",
        "program_code": "diploma"
      }
    ]
  }
}

Get School Term Grade Rubrics

get
/v2/school/term-rubrics

Retrieves the term grade rubrics configured for the School. Rubrics define the criteria or formulas used to calculate term grades. Each rubric includes its type (Criteria, Formula, or Custom Field), program code, and status. Criteria rubrics include their rubric options with values and descriptors. Formula rubrics specify the calculation method (AVG or SUM) and reference other rubric IDs.

Authorizations
AuthorizationstringRequired

OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.

Responses
200

Success

application/json
get/v2/school/term-rubrics
GET /v2/school/term-rubrics HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "school": {
    "term_rubrics": [
      {
        "id": 273,
        "title": "DP General Rubric 1",
        "program_code": "diploma",
        "rubric_type": "All Subjects",
        "type": "Criteria",
        "status": "active",
        "rubric_options": [
          {
            "id": 613,
            "value": "0",
            "descriptor": "Desc 0"
          },
          {
            "id": 614,
            "value": "1",
            "descriptor": "Desc 1"
          },
          {
            "id": 615,
            "value": "2",
            "descriptor": "Desc 2"
          }
        ]
      },
      {
        "id": 274,
        "title": "DP Subject Rubric 1",
        "program_code": "diploma",
        "rubric_type": "All Subjects",
        "type": "Criteria",
        "status": "active",
        "rubric_options": [
          {
            "id": 616,
            "value": "0",
            "descriptor": "Desc 0"
          },
          {
            "id": 617,
            "value": "1",
            "descriptor": "Desc 1"
          },
          {
            "id": 618,
            "value": "2",
            "descriptor": "Desc 2"
          }
        ]
      },
      {
        "id": 275,
        "title": "DP Avg Rubric 1",
        "program_code": "diploma",
        "rubric_type": "All Subjects",
        "type": "Formula",
        "formula": "AVG",
        "status": "active",
        "formula_rubric_ids": []
      },
      {
        "id": 276,
        "title": "DP Sum Rubric 1",
        "program_code": "diploma",
        "rubric_type": "All Subjects",
        "type": "Formula",
        "formula": "SUM",
        "status": "active",
        "formula_rubric_ids": [
          274
        ]
      },
      {
        "id": 277,
        "title": "DP Subject Rubric 2",
        "program_code": "diploma",
        "rubric_type": "All Subjects",
        "suffix": "-CF-",
        "type": "Custom Field",
        "status": "active"
      },
      {
        "id": 278,
        "title": "MYP General Rubric 1",
        "program_code": "myp",
        "rubric_type": "All Subjects",
        "type": "Criteria",
        "status": "active",
        "rubric_options": [
          {
            "id": 622,
            "value": "0",
            "descriptor": "Desc 0"
          },
          {
            "id": 623,
            "value": "1",
            "descriptor": "Desc 1"
          },
          {
            "id": 624,
            "value": "2",
            "descriptor": "Desc 2"
          }
        ]
      },
      {
        "id": 279,
        "title": "MYP Subject Rubric 1",
        "program_code": "myp",
        "rubric_type": "All Subjects",
        "type": "Criteria",
        "subject_id": 4119,
        "status": "active",
        "rubric_options": [
          {
            "id": 625,
            "value": "0",
            "descriptor": "Desc 0"
          },
          {
            "id": 626,
            "value": "1",
            "descriptor": "Desc 1"
          },
          {
            "id": 627,
            "value": "2",
            "descriptor": "Desc 2"
          }
        ]
      },
      {
        "id": 280,
        "title": "MYP Sum Rubric 1",
        "program_code": "myp",
        "rubric_type": "All Subjects",
        "type": "Formula",
        "formula": "SUM",
        "formula_rubric_ids": [],
        "status": "active"
      },
      {
        "id": 281,
        "title": "MYP Avg Rubric 1",
        "program_code": "myp",
        "rubric_type": "All Subjects",
        "type": "Formula",
        "formula": "AVG",
        "formula_rubric_ids": [],
        "status": "active"
      }
    ]
  }
}
Previousv2
NextYear Groups

Last updated