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

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`name` Query	String	Name for the badge

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Create a badge for a group

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

Creates a badge for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user

Request body (application/json)

Property	Type	Description
`image_url` Required	String	URL of the badge image
`link_url` Required	String	URL of the badge link
`name`	String	Name for the badge

Responses

Code	Description	Schema
`201`	Created	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

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

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user
`link_url` Query, required	String	URL of the badge link
`image_url` Query, required	String	URL of the badge image

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBasicBadgeDetails
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a badge for a group

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

Retrieves a specified badge for a group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Update a badge for a group

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

Updates a specified badge for a group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Request body (application/json)

Property	Type	Description
`image_url`	String	URL of the badge image
`link_url`	String	URL of the badge link
`name`	String	Name for the badge

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Delete a badge from a group

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

Deletes a specified badge from a group.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the group owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Responses

Code	Description	Schema
`204`	Resource deleted	—
`400`	Bad Request	—
`404`	Not Found	—

List all badges for a project

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

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

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`name` Query	String	Name for the badge

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Create a badge for a project

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

Creates a badge for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user

Request body (application/json)

Property	Type	Description
`image_url` Required	String	URL of the badge image
`link_url` Required	String	URL of the badge link
`name`	String	Name for the badge

Responses

Code	Description	Schema
`201`	Created	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

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

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user
`link_url` Query, required	String	URL of the badge link
`image_url` Query, required	String	URL of the badge image

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBasicBadgeDetails
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a badge for a project

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

Retrieves a specified badge for a project.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Update a badge for a project

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

Updates a specified badge for a project.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Request body (application/json)

Property	Type	Description
`image_url`	String	URL of the badge image
`link_url`	String	URL of the badge link
`name`	String	Name for the badge

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBadge
`400`	Bad Request	—
`404`	Not Found	—

Delete a badge from a project

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

Deletes a specified badge from a project.

Parameters

Name	Type	Description
`id` Path, required	String	The ID or URL-encoded path of the project owned by the authenticated user
`badge_id` Path, required	Integer	The badge ID

Responses

Code	Description	Schema
`204`	Resource deleted	—
`400`	Bad Request	—
`404`	Not Found	—

Schemas

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

APIEntitiesBadge

Property	Type	Description
`id`	Integer (int64)	Example: `1`
`image_url`	String	Example: `https://example.gitlab.com`
`kind`	String	Example: `project`
`link_url`	String	Example: `https://example.gitlab.com`
`name`	String	Example: `Pipeline Status`
`rendered_image_url`	String	Example: `https://example.gitlab.com`
`rendered_link_url`	String	Example: `https://example.gitlab.com`

APIEntitiesBasicBadgeDetails

Property	Type	Description
`image_url`	String	Example: `https://example.gitlab.com`
`link_url`	String	Example: `https://example.gitlab.com`
`name`	String	Example: `Pipeline Status`
`rendered_image_url`	String	Example: `https://example.gitlab.com`
`rendered_link_url`	String	Example: `https://example.gitlab.com`

Placeholders

List all badges for a group

Create a badge for a group

Retrieve a badge preview for a group

Retrieve a badge for a group

Update a badge for a group

Delete a badge from a group

List all badges for a project

Create a badge for a project

Retrieve a badge preview for a project

Retrieve a badge for a project

Update a badge for a project

Delete a badge from a project

Schemas

APIEntitiesBadge

APIEntitiesBasicBadgeDetails

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error