Skip to content

Group badges API

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Placeholder tokens

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

  • %{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.
  • %{default_branch}: replaced by the project default branch.
  • %{commit_sha}: replaced by the last project's commit SHA.

Because these endpoints aren't inside a project's context, the information used to replace the placeholders comes from the first group's project by creation date. If the group hasn't got any project the original URL with the placeholders is returned.

List all badges of a group

Gets a list of a group's badges.

GET /groups/:id/badges
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
name string no Name of the badges to return (case-sensitive). 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges?name=Coverage"

Example response:

[
  {
    "name": "Coverage",
    "id": 1,
    "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",
    "image_url": "https://shields.io/my/badge",
    "rendered_link_url": "http://example.com/ci_status.svg?project=example-org/example-project&ref=main",
    "rendered_image_url": "https://shields.io/my/badge",
    "kind": "group"
  }
]

Get a badge of a group

Gets a badge of a group.

GET /groups/:id/badges/:badge_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
badge_id integer yes The badge ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id"

Example response:

{
  "name": "Coverage",
  "id": 1,
  "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",
  "image_url": "https://shields.io/my/badge",
  "rendered_link_url": "http://example.com/ci_status.svg?project=example-org/example-project&ref=main",
  "rendered_image_url": "https://shields.io/my/badge",
  "kind": "group"
}

Add a badge to a group

Adds a badge to a group.

POST /groups/:id/badges
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
link_url string yes URL of the badge link
image_url string yes URL of the badge image
name string no Name of the badge 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge&position=0" \
     "https://gitlab.example.com/api/v4/groups/:id/badges"

Example response:

{
  "id": 1,
  "name": "mybadge",
  "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
  "image_url": "https://shields.io/my/badge1",
  "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
  "rendered_image_url": "https://shields.io/my/badge1",
  "kind": "group"
}

Edit a badge of a group

Updates a badge of a group.

PUT /groups/:id/badges/:badge_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
badge_id integer yes The badge ID
link_url string no URL of the badge link
image_url string no URL of the badge image
name string no Name of the badge 
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id"

Example response:

{
  "id": 1,
  "name": "mybadge",
  "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
  "image_url": "https://shields.io/my/badge",
  "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",
  "rendered_image_url": "https://shields.io/my/badge",
  "kind": "group"
}

Remove a badge from a group

Removes a badge from a group.

DELETE /groups/:id/badges/:badge_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
badge_id integer yes The badge ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id"

Preview a badge from a group

Returns how the link_url and image_url final URLs would be after resolving the placeholder interpolation.

GET /groups/:id/badges/render
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
link_url string yes URL of the badge link
image_url string yes URL of the badge image 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge"

Example response:

{
  "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",
  "image_url": "https://shields.io/my/badge",
  "rendered_link_url": "http://example.com/ci_status.svg?project=example-org/example-project&ref=main",
  "rendered_image_url": "https://shields.io/my/badge"
}