# GitLab Badges API

**Canonical:** https://apis.io/apis/gitlab/gitlab-badges-api/  
**Provider:** GitLab — https://apis.io/providers/gitlab/  
**Base URL:** https://gitlab.com/api/v4  
**Documentation:** https://docs.gitlab.com/api/rest/

GitLab Badges API is one of 189 APIs that [GitLab](https://apis.io/providers/gitlab/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 16 JSON Schema definitions. Tagged areas include Badges. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, authentication docs, an API reference, rate-limit docs, an AsyncAPI specification, and 16 JSON Schemas.

Use this API to manage badges for [projects](https://docs.gitlab.com/user/project/badges/) and [groups](https://docs.gitlab.com/user/project/badges/#group-badges). ## 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.

## Operations (12)

| Method | Path | Summary |
|---|---|---|
| GET | `/api/v4/groups/{id}/badges` | List all badges for a group |
| POST | `/api/v4/groups/{id}/badges` | Create a badge for a group |
| GET | `/api/v4/groups/{id}/badges/render` | Retrieve a badge preview for a group |
| GET | `/api/v4/groups/{id}/badges/{badge_id}` | Retrieve a badge for a group |
| PUT | `/api/v4/groups/{id}/badges/{badge_id}` | Update a badge for a group |
| DELETE | `/api/v4/groups/{id}/badges/{badge_id}` | Delete a badge from a group |
| GET | `/api/v4/projects/{id}/badges` | List all badges for a project |
| POST | `/api/v4/projects/{id}/badges` | Create a badge for a project |
| GET | `/api/v4/projects/{id}/badges/render` | Retrieve a badge preview for a project |
| GET | `/api/v4/projects/{id}/badges/{badge_id}` | Retrieve a badge for a project |
| PUT | `/api/v4/projects/{id}/badges/{badge_id}` | Update a badge for a project |
| DELETE | `/api/v4/projects/{id}/badges/{badge_id}` | Delete a badge from a project |

## Machine-readable artifacts (65)

- **OpenAPI** — https://artifacts.apis.io/gitlab/openapi/gitlab-badges-api-openapi.yml
- **Documentation** — https://docs.gitlab.com/api/openapi/
- **Documentation** — https://docs.gitlab.com/api/issues/
- **Authentication** — https://docs.gitlab.com/api/rest/authentication/
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-application-settings-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-node-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-site-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-application-setting-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-post-api-v4-geo-status-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-projects-id-request-schema.json
- **Documentation** — https://docs.gitlab.com/api/merge_requests/
- **Documentation** — https://docs.gitlab.com/api/pipelines/
- **Documentation** — https://docs.gitlab.com/api/jobs/
- **Documentation** — https://docs.gitlab.com/api/runners/
- **Documentation** — https://docs.gitlab.com/api/users/
- **Documentation** — https://docs.gitlab.com/api/repositories/
- **Documentation** — https://docs.gitlab.com/api/commits/
- **Documentation** — https://docs.gitlab.com/api/branches/
- **Documentation** — https://docs.gitlab.com/api/tags/
- **Documentation** — https://docs.gitlab.com/api/releases/
- **Documentation** — https://docs.gitlab.com/api/environments/
- **Documentation** — https://docs.gitlab.com/api/deployments/
- **Documentation** — https://docs.gitlab.com/api/pipeline_schedules/
- **Documentation** — https://docs.gitlab.com/api/labels/
- **Documentation** — https://docs.gitlab.com/api/milestones/
- **Documentation** — https://docs.gitlab.com/api/notes/
- **Documentation** — https://docs.gitlab.com/api/snippets/
- **Documentation** — https://docs.gitlab.com/api/packages/
- **Documentation** — https://docs.gitlab.com/api/container_registry/
- **Documentation** — https://docs.gitlab.com/api/vulnerabilities/
- **Documentation** — https://docs.gitlab.com/api/deploy_keys/
- **Documentation** — https://docs.gitlab.com/api/protected_branches/
- **Documentation** — https://docs.gitlab.com/api/wikis/
- **Documentation** — https://docs.gitlab.com/api/events/
- **Documentation** — https://docs.gitlab.com/api/search/
- **Documentation** — https://docs.gitlab.com/api/namespaces/
- **Documentation** — https://docs.gitlab.com/api/groups/
- **Documentation** — https://docs.gitlab.com/api/projects/
- **Documentation** — https://docs.gitlab.com/api/applications/
- **Documentation** — https://docs.gitlab.com/api/avatar/
- …and 25 more, listed in full on the page.

## Other GitLab APIs (12)

- [GitLab Orbit gRPC API](https://apis.io/apis/gitlab/gitlab-orbit-api/)
- [GitLab GraphQL API](https://apis.io/apis/gitlab/gitlab-graphql-api/)
- [GitLab Applications API](https://apis.io/apis/gitlab/gitlab-applications-api/)
- [GitLab Authorization API](https://apis.io/apis/gitlab/gitlab-authorization-api/)
- [GitLab Broadcast Messages API](https://apis.io/apis/gitlab/gitlab-broadcast-messages-api/)
- [GitLab Groups API](https://apis.io/apis/gitlab/gitlab-groups-api/)
- [GitLab Metadata API](https://apis.io/apis/gitlab/gitlab-metadata-api/)
- [GitLab Project Webhooks API](https://apis.io/apis/gitlab/gitlab-project-webhooks-api/)
- [GitLab Projects API](https://apis.io/apis/gitlab/gitlab-projects-api/)
- [GitLab Tokens API](https://apis.io/apis/gitlab/gitlab-tokens-api/)
- [GitLab User Info API](https://apis.io/apis/gitlab/gitlab-user-info-api/)
- [GitLab Webhook Configuration API](https://apis.io/apis/gitlab/gitlab-webhook-configuration-api/)

## Tags

Badges

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/gitlab/gitlab-badges-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/gitlab/.