Project badges API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Version history

  • CI/CD job token authentication introduced in GitLab 19.1.

Use this API to manage project badges.

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.

List all badges of a project

Lists all badges for a project, including group badges.

GET /projects/:id/badges
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
name string no Name of the badges to return (case-sensitive). 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/: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": "project"
  },
  {
    "name": "Pipeline",
    "id": 2,
    "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"
  }
]

Retrieve a badge of a project

Retrieves a badge of a project.

GET /projects/:id/badges/:badge_id
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
badge_id integer yes The badge ID 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/: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": "project"
}

Create a badge for a project

Creates a badge for a project.

POST /projects/:id/badges
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
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>" \
  --form "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/main" \
  --form "image_url=https://shields.io/my/badge1" \
  --form "name=mybadge" \
  --url "https://gitlab.example.com/api/v4/projects/:id/badges"

Example response:

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

Update a badge of a project

Updates a badge of a project.

PUT /projects/:id/badges/:badge_id
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
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>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id"

Example response:

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

Delete a badge from a project

Deletes a badge from a project. To delete group badges, use the Group badges API instead.

DELETE /projects/:id/badges/:badge_id
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
badge_id integer yes The badge ID 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id"

Preview a badge from a project

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

GET /projects/:id/badges/render
Attribute Type Required Description
id integer or string yes The ID or URL-encoded path of the project
link_url string yes URL of the badge link
image_url string yes URL of the badge image 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/: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"
}