Manage image templates
An image template is a named image slot with a fixed pixel size, for example a 640x360 team banner or
a 1080x1350 player cut-out. Each template is for one entity type: player, team or competition.
It is also for one sport. A theme binds a template into its graphics. Each player, team or
competition can then hold one image for that template.
Template reads need the images:read scope, and template changes need images:write. Image calls on
a player, team or competition need the scope of that entity, for example teams:write. The endpoints are under
Image templates in the REST reference.
Templates, logos and photos
Section titled “Templates, logos and photos”A team logo and a player photo are direct images. Each entity has at most one of each. The size is
fixed by LIGR. Set a team logo with PUT /v1/teams/{teamId}/logo. See
Set up through REST.
Use a template when a graphic needs a different image. Examples are a wide banner, a sponsor
version of a crest, or a transparent player cut-out. You choose the name and the size. A template can
also hold a default image. A Rive graphic can use it as the fallback image of an exposed asset: send
the template’s defaultFileId as defaultFileId on the exposure. See
Images, preview and evaluate.
| Direct logo or photo | Image template | |
|---|---|---|
| Images per entity | One | One per template |
| Size | Fixed by LIGR | Fixed by the template |
| Fallback | Club logo, for a team | Optional default image, per template |
| Used by | Every graphic that shows the logo or photo | Graphics that the theme binds to the template |
Create and manage a template
Section titled “Create and manage a template”-
Create the template.
The size, the entity type and the sport cannot change later.
widthandheightare whole pixels from 1 to 8192.Terminal curl -X POST 'https://api.ligr.live/rest/v1/image-templates' \-H "Authorization: Bearer $LIGR_API_KEY" \-H 'Content-Type: application/json' \-d '{ "name": "Team banner", "width": 640, "height": 360, "entityType": "team", "sport": "football" }'201 Created {"id": 87,"name": "Team banner","width": 640,"height": 360,"entityType": "team","sport": "football","defaultImageUrl": null,"defaultFileId": null,"createdAt": "2026-09-30T04:12:09.000Z","updatedAt": "2026-09-30T04:12:09.000Z"} -
Set a default image.
The default image uses the same two-call upload as a team logo. Use a PNG or JPEG file of 5 MB or less. Its pixel size must equal the template size.
Terminal IMAGE=banner.pngSESSION=$(curl -s -X POST "https://api.ligr.live/rest/v1/image-templates/87/default-image/uploads" \-H "Authorization: Bearer $LIGR_API_KEY" -H 'Content-Type: application/json' \-d "$(jq -n --argjson size "$(wc -c < "$IMAGE" | tr -d ' ')" \--arg sha256 "$(shasum -a 256 "$IMAGE" | cut -d ' ' -f 1)" \'{contentType: "image/png", size: $size, sha256: $sha256}')")curl --fail-with-body -X PUT "$(jq -er '.url' <<< "$SESSION")" \-H "x-amz-checksum-sha256: $(jq -er '.headers["x-amz-checksum-sha256"]' <<< "$SESSION")" \--data-binary "@$IMAGE"curl -X PUT "https://api.ligr.live/rest/v1/image-templates/87/default-image" \-H "Authorization: Bearer $LIGR_API_KEY" -H 'Content-Type: application/json' \-d "{\"uploadId\": $(jq -er '.uploadId' <<< "$SESSION")}"Do the PUT to
urlbeforeexpiresAt. Send theuploadIdwithin one hour. The API checks the size, the SHA-256, the image type and the pixel size. An image of another pixel size returns 400 withcode: "IMAGE_DIMENSIONS_MISMATCH". Each upload sets a default image one time. To remove the default image, sendDELETE /v1/image-templates/87/default-image. -
Rename the template.
Only the name can change. Send
PATCH /v1/image-templates/87with{ "name": "Team banner wide" }. -
Read what uses the template.
GET /v1/image-templates/87returns the template withusage.instanceCountis the number of entity images that the template holds. See Set entity images.themeMappingslists each competition theme setting that binds the template into a graphic. -
Delete the template.
Send
DELETE /v1/image-templates/87. A template in use returns 409 withcode: "IMAGE_TEMPLATE_IN_USE"and the sameusage. Remove the entity images and the theme mappings first, then delete again. To remove an entity image, see Set entity images.
List templates
Section titled “List templates”GET /v1/image-templates returns a page of your templates, sorted by id. Filter with entityType
and sport. Page with limit (1 to 500, default 200) and offset. The answer holds
imageTemplates, total and returned.
Set entity images
Section titled “Set entity images”Each player, team or competition can hold one image for each template of its entity type. The routes are under the entity:
| Entity | Routes |
|---|---|
| Player | /v1/players/{playerId}/images |
| Team | /v1/teams/{teamId}/images |
| Competition | /v1/competitions/{competitionId}/images |
The examples below use team 12 and the team banner template 87. Players and competitions use the same calls under their own path.
-
List the images of the entity.
GET /v1/teams/12/imagesreturns one item for each team template of your organization, sorted by template id. This call needs theteams:readscope.200 OK {"images": [{"imageTemplateId": 87,"templateName": "Team banner","width": 640,"height": 360,"url": null,"defaultImageUrl": null}]}urlis null when the team has no image for the template.defaultImageUrlis null when the template has no default image. -
Set the image.
The image uses the same two-call upload as the default image. Use a PNG or JPEG file of 5 MB or less. Its pixel size must equal the template size.
Terminal IMAGE=banner.pngSESSION=$(curl -s -X POST "https://api.ligr.live/rest/v1/teams/12/images/87/uploads" \-H "Authorization: Bearer $LIGR_API_KEY" -H 'Content-Type: application/json' \-d "$(jq -n --argjson size "$(wc -c < "$IMAGE" | tr -d ' ')" \--arg sha256 "$(shasum -a 256 "$IMAGE" | cut -d ' ' -f 1)" \'{contentType: "image/png", size: $size, sha256: $sha256}')")curl --fail-with-body -X PUT "$(jq -er '.url' <<< "$SESSION")" \-H "x-amz-checksum-sha256: $(jq -er '.headers["x-amz-checksum-sha256"]' <<< "$SESSION")" \--data-binary "@$IMAGE"curl -X PUT "https://api.ligr.live/rest/v1/teams/12/images/87" \-H "Authorization: Bearer $LIGR_API_KEY" -H 'Content-Type: application/json' \-d "{\"uploadId\": $(jq -er '.uploadId' <<< "$SESSION")}"The answer is the item for the template, with
urlset. Send the same calls again to replace the image. Live overlays show the new image. -
Remove the image.
Send
DELETE /v1/teams/12/images/87. The answer is the item for the template, withurlnull.
These errors apply to all three entity types:
| Status | Cause |
|---|---|
400 INVALID_INPUT | The template is for another entity type, for example a player template on a team route. |
400 IMAGE_DIMENSIONS_MISMATCH | The pixel size of the image is not the template size. |
| 403 | The entity or the template belongs to another organization, or the key has no write scope for the entity, for example teams:write. |
| 404 | The entity or the template does not exist, or the uploadId is not a pending upload of the template. |