> For the complete documentation index, see [llms.txt](https://developers.jarsave.com/llms.txt)

# Term reports

## The term report object

The report a teacher writes at the end of a term or a block of meetings. Send its scores and teacher notes as fields, not only inside the PDF: JarSave reads them to give the parent ideas for helping at home.

### Attributes

- `report_id` string required: Your id for this report.
- `course_id` string required: Your id for the course.
- `course_name` string required: The course as the parent knows it.
- `period_start` date required: The first day the report covers.
- `period_end` date required: The last day it covers.
- `meeting_from` integer, nullable: The first meeting it covers, for example `14`.
- `meeting_to` integer, nullable: The last meeting it covers, for example `21`.
- `issued_on` date required: The day the report was published.
- `criteria` array of objects required: One row per criterion the teacher assessed.
  - `name` string required: The criterion, for example `Coding Concept & Practice`.
  - `score` integer, nullable required: 0 to 100, or null if the criterion has only a grade.
  - `grade` string required: The grade as printed, for example `A`.
  - `teacher_note` string required: The teacher's words for this criterion, unedited.
- `lessons` array of objects: The lesson scores the report lists.
  - `meeting_no` integer required: The meeting the lesson was in.
  - `title` string required: The lesson's title.
  - `score` integer required: 0 to 100.
  - `grade` string required: The grade as printed.
- `grading_scale` array of objects required: Your grades and what they mean, so the parent can read them.
  - `grade` string required: For example `A`.
  - `min` integer required: The lowest score for this grade.
  - `max` integer required: The highest score for this grade.
  - `label` string required: For example `Very Good`.
- `summary` object: Totals for the period, as the report prints them: `hours`, `projects`, `skills_gained`.
- `signed_by` object required: Who signed the report: `name` and `role`, for example `Head of Teachers`.
- `file_url` string required: The report as PDF. See [files](https://developers.jarsave.com/data.md).

**The term report object**

```json
{
  "report_id": "rpt_20931",
  "course_id": "crs_junior_coding_2",
  "course_name": "Junior Coding 2",
  "period_start": "2026-09-03",
  "period_end": "2026-10-22",
  "meeting_from": 1,
  "meeting_to": 7,
  "issued_on": "2026-10-29",
  "criteria": [
    {
      "name": "Coding Concept & Practice",
      "score": 92,
      "grade": "A",
      "teacher_note": "Uses loops with confidence and explains them in her own words."
    }
  ],
  "lessons": [
    { "meeting_no": 3, "title": "Make the Robot Dance", "score": 86, "grade": "A" }
  ],
  "grading_scale": [
    { "grade": "A", "min": 86, "max": 100, "label": "Very Good" },
    { "grade": "B", "min": 75, "max": 85, "label": "Good" }
  ],
  "summary": { "hours": 10.5, "projects": 4, "skills_gained": 3 },
  "signed_by": { "name": "Dewi Anggraini", "role": "Head of Teachers" },
  "file_url": "https://files.academy.example/r/20931.pdf?sig=..."
}
```

## Send a term report

`POST /v1/links/:id/reports`

Send a report on the day you publish it to families. For the history, send every report of the student's courses so far when the link becomes `active`.

### Parameters

The term report object's attributes, one report per request.

### Returns

The item with its JarSave `id`, `link`, `status` and `received`.

**Request**

```sh
curl https://api.jarsave.com/v1/links/lnk_8Gm2QxT4/reports \
  -H "Authorization: Bearer $JARSAVE_SECRET_KEY" \
  -H "JarSave-Version: 2026-10-29" \
  -H "Content-Type: application/json" \
  -d @report.json
```

**Response**

```json
{
  "id": "itm_2Wd8Ms5N",
  "object": "report",
  "link": "lnk_8Gm2QxT4",
  "report_id": "rpt_20931",
  "status": "pending",
  "received": "2026-10-29T10:20:15+07:00"
}
```