Skip to content

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.

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 photoImage template
Images per entityOneOne per template
SizeFixed by LIGRFixed by the template
FallbackClub logo, for a teamOptional default image, per template
Used byEvery graphic that shows the logo or photoGraphics that the theme binds to the template
  1. Create the template.

    The size, the entity type and the sport cannot change later. width and height are 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"
    }
  2. 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.png
    SESSION=$(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 url before expiresAt. Send the uploadId within 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 with code: "IMAGE_DIMENSIONS_MISMATCH". Each upload sets a default image one time. To remove the default image, send DELETE /v1/image-templates/87/default-image.

  3. Rename the template.

    Only the name can change. Send PATCH /v1/image-templates/87 with { "name": "Team banner wide" }.

  4. Read what uses the template.

    GET /v1/image-templates/87 returns the template with usage. instanceCount is the number of entity images that the template holds. See Set entity images. themeMappings lists each competition theme setting that binds the template into a graphic.

  5. Delete the template.

    Send DELETE /v1/image-templates/87. A template in use returns 409 with code: "IMAGE_TEMPLATE_IN_USE" and the same usage. Remove the entity images and the theme mappings first, then delete again. To remove an entity image, see Set entity images.

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.

Each player, team or competition can hold one image for each template of its entity type. The routes are under the entity:

EntityRoutes
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.

  1. List the images of the entity.

    GET /v1/teams/12/images returns one item for each team template of your organization, sorted by template id. This call needs the teams:read scope.

    200 OK
    {
    "images": [
    {
    "imageTemplateId": 87,
    "templateName": "Team banner",
    "width": 640,
    "height": 360,
    "url": null,
    "defaultImageUrl": null
    }
    ]
    }

    url is null when the team has no image for the template. defaultImageUrl is null when the template has no default image.

  2. 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.png
    SESSION=$(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 url set. Send the same calls again to replace the image. Live overlays show the new image.

  3. Remove the image.

    Send DELETE /v1/teams/12/images/87. The answer is the item for the template, with url null.

These errors apply to all three entity types:

StatusCause
400 INVALID_INPUTThe template is for another entity type, for example a player template on a team route.
400 IMAGE_DIMENSIONS_MISMATCHThe pixel size of the image is not the template size.
403The entity or the template belongs to another organization, or the key has no write scope for the entity, for example teams:write.
404The entity or the template does not exist, or the uploadId is not a pending upload of the template.