GitLab

GitLab Groups API

The Groups API from GitLab — 6 operation(s) for groups.

Documentation GitHub OpenAPI

Operations 10

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v4/groups/{id}/badges/{badge_id} Get a group badge · GitLab Gets a Badge of a Group #

Ask an LLM

“How do I look up a single badge defined on a group?”

“What link and image does a specific group badge point to?”

Tell an agent

Show group badge {badge_id} in group {id}.

Get the URLs of badge {badge_id} on group {id}.

PUT /api/v4/groups/{id}/badges/{badge_id} Update a group badge · GitLab Updates a Badge of a Group #

Ask an LLM

“How do I change the image or link on a badge shared across a group?”

“Can I rename an existing group badge?”

Tell an agent

Change the image URL of group badge {badge_id} in group {id} to {image_url}.

Point group badge {badge_id} of group {id} at {link_url}.

DELETE /api/v4/groups/{id}/badges/{badge_id} Remove a badge from a group · GitLab Removes a Badge from the Group #

Ask an LLM

“How do I delete a badge that shows on every project in a group?”

“Can I remove one group-level badge by ID?”

Tell an agent destructive · confirm first

Remove badge {badge_id} from group {id}.

Delete the group badge {badge_id} in group {id}.

GET /api/v4/groups/{id}/badges List a group's badges · GitLab Gets a List of Group Badges Viewable by the Authenticated User #

Ask an LLM

“Which badges are defined at the group level?”

“Can I filter a group's badges by name?”

Tell an agent

List the badges on group {id}.

Find group badges named {name} in group {id}.

POST /api/v4/groups/{id}/badges Add a badge to a group · GitLab Adds a Badge to a Group #

Ask an LLM

“How do I add a badge that appears on all projects in a GitLab group?”

“What is required to create a group-level badge?”

Tell an agent

Add a badge to group {id} linking to {link_url} with image {image_url}.

Create a group badge {name} on group {id} with image {image_url} and link {link_url}.

GET /api/v4/groups/{id}/badges/render Preview how a group badge will render · GitLab Preview a Badge from a Group #

Ask an LLM

“Can I preview a group badge's resolved URLs before saving it?”

“How do I test badge URL placeholders against a group?”

Tell an agent

Preview a group badge for group {id} with link {link_url} and image {image_url}.

Render group badge URLs {image_url} and {link_url} for group {id} without saving.

DELETE /api/v4/groups/{id}/access_requests/{user_id} Deny a user's request to join a group · GitLab Denies an Access Request for the Given User #

Ask an LLM

“How do I reject someone's request to join my group?”

“Can I deny a pending group membership request?”

Tell an agent destructive · confirm first

Deny user {user_id}'s request to join group {id}.

Reject the group access request from {user_id} on group {id}.

PUT /api/v4/groups/{id}/access_requests/{user_id}/approve Approve a user's request to join a group · GitLab Approves an Access Request for the Given User #

Ask an LLM

“How do I approve a pending request to join a group?”

“Can I set the member's role when approving a group access request?”

Tell an agent

Approve user {user_id}'s request to join group {id}.

Admit {user_id} to group {id} at access level {access_level}.

GET /api/v4/groups/{id}/access_requests List pending access requests for a group · GitLab Gets a List of Access Requests for a Group #

Ask an LLM

“Who is waiting for approval to join my group?”

“Where do I see outstanding group membership requests?”

Tell an agent

List pending access requests for group {id}.

Show who has asked to join group {id}.

POST /api/v4/groups/{id}/access_requests Request access to a group for yourself · GitLab Requests Access for the Authenticated User to a Group #

Ask an LLM

“How do I ask to become a member of a GitLab group?”

“Can I file a group access request for my own account?”

Tell an agent

Request access to group {id} for me.

Submit my request to join group {id}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/gitlab:gitlab-groups-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: GitLab Groups API
  version: v4
  description: An OpenAPI definition for the GitLab REST API.
  termsOfService: https://about.gitlab.com/terms/
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
servers:
- url: https://www.gitlab.com/api/
security:
- ApiKeyAuth: []
tags:
- name: Groups
paths:
  /api/v4/groups/{id}/badges/{badge_id}:
    get:
      tags:
      - Groups
      summary: GitLab Gets a Badge of a Group
      description: This feature was introduced in GitLab 10.6.
      operationId: getApiV4GroupsIdBadgesBadgeId
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      - name: badge_id
        in: path
        description: The badge ID
        required: true
        schema:
          type: integer
          format: int32
        example: 42
      responses:
        '200':
          description: Gets a badge of a group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Badge'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Groups
      summary: GitLab Updates a Badge of a Group
      description: This feature was introduced in GitLab 10.6.
      operationId: putApiV4GroupsIdBadgesBadgeId
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      - name: badge_id
        in: path
        required: true
        schema:
          type: integer
          format: int32
        example: 42
      requestBody:
        content:
          application/json:
            schema:
              properties:
                link_url:
                  type: string
                  description: URL of the badge link
                image_url:
                  type: string
                  description: URL of the badge image
                name:
                  type: string
                  description: Name for the badge
      responses:
        '200':
          description: Updates a badge of a group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Badge'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Groups
      summary: GitLab Removes a Badge from the Group
      description: This feature was introduced in GitLab 10.6.
      operationId: deleteApiV4GroupsIdBadgesBadgeId
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      - name: badge_id
        in: path
        description: The badge ID
        required: true
        schema:
          type: integer
          format: int32
        example: 42
      responses:
        '204':
          description: Removes a badge from the group.
          content: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v4/groups/{id}/badges:
    get:
      tags:
      - Groups
      summary: GitLab Gets a List of Group Badges Viewable by the Authenticated User
      description: This feature was introduced in GitLab 10.6.
      operationId: getApiV4GroupsIdBadges
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      - name: page
        in: query
        description: Current page number
        schema:
          type: integer
          format: int32
          default: 1
        example: 42
      - name: per_page
        in: query
        description: Number of items per page
        schema:
          type: integer
          format: int32
          default: 20
        example: 42
      - name: name
        in: query
        description: Name for the badge
        schema:
          type: string
        example: Example Project
      responses:
        '200':
          description: Gets a list of group badges viewable by the authenticated user.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/API_Entities_Badge'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Groups
      summary: GitLab Adds a Badge to a Group
      description: This feature was introduced in GitLab 10.6.
      operationId: postApiV4GroupsIdBadges
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - image_url
              - link_url
              properties:
                link_url:
                  type: string
                  description: URL of the badge link
                image_url:
                  type: string
                  description: URL of the badge image
                name:
                  type: string
                  description: Name for the badge
        required: true
      responses:
        '201':
          description: Adds a badge to a group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Badge'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v4/groups/{id}/badges/render:
    get:
      tags:
      - Groups
      summary: GitLab Preview a Badge from a Group
      description: This feature was introduced in GitLab 10.6.
      operationId: getApiV4GroupsIdBadgesRender
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user.
        required: true
        schema:
          type: string
        example: '123456'
      - name: link_url
        in: query
        description: URL of the badge link
        required: true
        schema:
          type: string
        example: https://gitlab.com/example
      - name: image_url
        in: query
        description: URL of the badge image
        required: true
        schema:
          type: string
        example: https://gitlab.com/example
      responses:
        '200':
          description: Preview a badge from a group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_BasicBadgeDetails'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v4/groups/{id}/access_requests/{user_id}:
    delete:
      tags:
      - Groups
      summary: GitLab Denies an Access Request for the Given User
      description: This feature was introduced in GitLab 8.11.
      operationId: deleteApiV4GroupsIdAccessRequestsUserId
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user
        required: true
        schema:
          type: string
        example: '123456'
      - name: user_id
        in: path
        description: The user ID of the access requester
        required: true
        schema:
          type: integer
          format: int32
        example: 42
      responses:
        '204':
          description: Denies an access request for the given user.
          content: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v4/groups/{id}/access_requests/{user_id}/approve:
    put:
      tags:
      - Groups
      summary: GitLab Approves an Access Request for the Given User
      description: This feature was introduced in GitLab 8.11.
      operationId: putApiV4GroupsIdAccessRequestsUserIdApprove
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user
        required: true
        schema:
          type: string
        example: '123456'
      - name: user_id
        in: path
        description: The user ID of the access requester
        required: true
        schema:
          type: integer
          format: int32
        example: 42
      requestBody:
        content:
          application/json:
            schema:
              properties:
                access_level:
                  type: integer
                  description: 'A valid access level (defaults: `30`, the Developer role)'
                  format: int32
                  default: 30
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_AccessRequester'
            successfull_response:
              example:
                id: 1
                username: raymond_smith
                name: Raymond Smith
                state: active
                created_at: 2012-10-22 14:13:35+00:00
                access_level: 20
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v4/groups/{id}/access_requests:
    get:
      tags:
      - Groups
      summary: GitLab Gets a List of Access Requests for a Group
      description: This feature was introduced in GitLab 8.11.
      operationId: getApiV4GroupsIdAccessRequests
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user
        required: true
        schema:
          type: string
        example: '123456'
      - name: page
        in: query
        description: Current page number
        schema:
          type: integer
          format: int32
          default: 1
        example: 42
      - name: per_page
        in: query
        description: Number of items per page
        schema:
          type: integer
          format: int32
          default: 20
        example: 42
      responses:
        '200':
          description: Gets a list of access requests for a group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_AccessRequester'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Groups
      summary: GitLab Requests Access for the Authenticated User to a Group
      description: This feature was introduced in GitLab 8.11.
      operationId: postApiV4GroupsIdAccessRequests
      parameters:
      - name: id
        in: path
        description: The ID or URL-encoded path of the group owned by the authenticated user
        required: true
        schema:
          type: string
        example: '123456'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_AccessRequester'
            successfull_response:
              example:
                id: 1
                username: raymond_smith
                name: Raymond Smith
                state: active
                created_at: 2012-10-22 14:13:35+00:00
                access_level: 20
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    API_Entities_BasicBadgeDetails:
      type: object
      properties:
        name:
          type: string
          example: Example Project
        link_url:
          type: string
          example: https://gitlab.com/example
        image_url:
          type: string
          example: https://gitlab.com/example
        rendered_link_url:
          type: string
          example: https://gitlab.com/example
        rendered_image_url:
          type: string
          example: https://gitlab.com/example
      description: API_Entities_BasicBadgeDetails model
    API_Entities_AccessRequester:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        username:
          type: string
          example: admin
        name:
          type: string
          example: Administrator
        state:
          type: string
          example: active
        avatar_url:
          type: string
          example: https://gravatar.com/avatar/1
        avatar_path:
          type: string
          example: /user/avatar/28/The-Big-Lebowski-400-400.png
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/API_Entities_CustomAttribute'
        web_url:
          type: string
          example: https://gitlab.example.com/root
        email:
          type: string
          example: user@example.com
        requested_at:
          type: string
          example: '2026-04-17T12:00:00Z'
      description: API_Entities_AccessRequester model
    API_Entities_Badge:
      type: object
      properties:
        name:
          type: string
          example: Example Project
        link_url:
          type: string
          example: https://gitlab.com/example
        image_url:
          type: string
          example: https://gitlab.com/example
        rendered_link_url:
          type: string
          example: https://gitlab.com/example
        rendered_image_url:
          type: string
          example: https://gitlab.com/example
        id:
          type: string
          example: '123456'
        kind:
          type: string
          example: example_value
      description: API_Entities_Badge model
    API_Entities_CustomAttribute:
      type: object
      properties:
        key:
          type: string
          example: foo
        value:
          type: string
          example: bar
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Private-Token

GitLab Groups API

Operations 10

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification