For AI agents: a documentation index is available at https://developers.jarsave.com/llms.txt, this page as Markdown at https://developers.jarsave.com/badges.md, and the OpenAPI description at https://developers.jarsave.com/openapi.json.
The badge object
v1A 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.
earned_at timestamp Required
When the student earned it.
The badge object
{
"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
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.jsonuse Illuminate\Support\Facades\Http;
// config/services.php: 'jarsave' => ['key' => env('JARSAVE_SECRET_KEY')]
// $badge: an array with the fields shown above
$response = Http::withToken(config('services.jarsave.key'))
->withHeaders(['JarSave-Version' => '2026-10-29'])
->post('https://api.jarsave.com/v1/links/lnk_8Gm2QxT4/badges', $badge);// badge: an object with the fields shown above
const response = await fetch("https://api.jarsave.com/v1/links/lnk_8Gm2QxT4/badges", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.JARSAVE_SECRET_KEY}`,
"JarSave-Version": "2026-10-29",
"Content-Type": "application/json",
},
body: JSON.stringify(badge),
});
const result = await response.json();import os
import requests
# badge: a dict with the fields shown above
response = requests.post(
"https://api.jarsave.com/v1/links/lnk_8Gm2QxT4/badges",
headers={
"Authorization": f"Bearer {os.environ['JARSAVE_SECRET_KEY']}",
"JarSave-Version": "2026-10-29",
},
json=badge,
timeout=30,
)
result = response.json()