Badges

Use this API to manage badges for projects and groups.

Placeholders

Badges support placeholders that are replaced in real time in both the link and image URL. The following placeholders are available:

• %{project_path}: replaced by the project path.
• %{project_title}: replaced by the project title.
• %{project_name}: replaced by the project name.
• %{project_id}: replaced by the project ID.
• %{project_namespace}: replaced by the project’s namespace full path.
• %{group_name}: replaced by the project’s top-level group name.
• %{gitlab_server}: replaced by the project’s server name.
• %{gitlab_pages_domain}: replaced by the domain name hosting GitLab Pages.
• %{default_branch}: replaced by the project default branch.
• %{commit_sha}: replaced by the project’s last commit SHA.
• %{latest_tag}: replaced by the project’s last tag.

Group badge endpoints operate outside a project’s context, so placeholder values are taken from the group’s earliest-created project. If no projects exist in the group, the URL is returned unchanged.

List all badges for a group

GET /api/v4/groups/{id}/badges

Lists all badges for a specified group.

Parameters

Responses

Create a badge for a group

POST /api/v4/groups/{id}/badges

Creates a badge for a specified group.

Parameters

Request body (application/json)

Responses

Retrieve a badge preview for a group

GET /api/v4/groups/{id}/badges/render

Previews the final link_url and image_url for a specified group after resolving the placeholder interpolation.

Parameters

Responses

Retrieve a badge for a group

GET /api/v4/groups/{id}/badges/{badge_id}

Retrieves a specified badge for a group.

Parameters

Responses

Update a badge for a group

PUT /api/v4/groups/{id}/badges/{badge_id}

Updates a specified badge for a group.

Parameters

Request body (application/json)

Responses

Delete a badge from a group

DELETE /api/v4/groups/{id}/badges/{badge_id}

Deletes a specified badge from a group.

Parameters

Responses

List all badges for a project

GET /api/v4/projects/{id}/badges

Lists all badges for a specified project, including group badges.

Parameters

Responses

Create a badge for a project

POST /api/v4/projects/{id}/badges

Creates a badge for a specified project.

Parameters

Request body (application/json)

Responses

Retrieve a badge preview for a project

GET /api/v4/projects/{id}/badges/render

Previews the final link_url and image_url for a specified project after resolving the placeholder interpolation.

Parameters

Responses

Retrieve a badge for a project

GET /api/v4/projects/{id}/badges/{badge_id}

Retrieves a specified badge for a project.

Parameters

Responses

Update a badge for a project

PUT /api/v4/projects/{id}/badges/{badge_id}

Updates a specified badge for a project.

Parameters

Request body (application/json)

Responses

Delete a badge from a project

DELETE /api/v4/projects/{id}/badges/{badge_id}

Deletes a specified badge from a project.

Parameters

Responses

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBadge

APIEntitiesBasicBadgeDetails