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

# Badges

## The badge object

A badge or achievement the student earned in your system. Send only badges the student has earned, not the ones still locked.

### Attributes

- `badge_id` string required: Your id for this student's badge.
- `name` string required: The badge's name, for example `3D Builder`.
- `subject` string required: What it is for, in one or two words, for example `Coding`.
- `course_id` string, nullable: The course it belongs to, if any.
- `image_url` string required: The badge picture, PNG or SVG, square, at least 256 pixels. See [files](https://developers.jarsave.com/data.md).
- `earned_at` timestamp required: When the student earned it.

**The badge object**

```json
{
  "badge_id": "bdg_3d_builder_1024",
  "name": "3D Builder",
  "subject": "Coding",
  "course_id": "crs_junior_coding_2",
  "image_url": "https://files.academy.example/b/3d-builder.png",
  "earned_at": "2027-01-28T16:30:00+07:00"
}
```

## Send a badge

`POST /v1/links/:id/badges`

Send a badge when the student earns it, and every earned badge once when the link becomes `active`.

### Parameters

The badge object's attributes, or up to 100 of them in an `items` array.

### Returns

The item with its JarSave `id`, `link`, `status` and `received`. With `items`, a list: `{"object": "list", "data": [...]}`, one entry per item in the order sent.

**Request**

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