The GitLab REST API provides programmatic access to GitLab resources, enabling you to build integrations, automate repetitive tasks, and extract data for custom reports. The API supports projects, groups, issues, merge requests, CI/CD pipelines, and many other GitLab features through standard HTTP methods and JSON responses.
openapi: 3.0.1
info:
title: GitLab API
version: v4
description: >
An OpenAPI definition for the GitLab REST API.
Few API resources or endpoints are currently included.
The intent is to expand this to match the entire Markdown documentation of
the API:
<https://docs.gitlab.com/ee/api/>. Contributions are welcome.
When viewing this on gitlab.com, you can test API calls directly from the
browser
against the `gitlab.com` instance, if you are logged in.
The feature uses the current [GitLab session
cookie](https://docs.gitlab.com/ee/api/index.html#session-cookie),
so each request is made using your account.
Instructions for using this tool can be found in [Interactive API
Documentation](https://docs.gitlab.com/ee/api/openapi/openapi_interactive.html)
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: Admin
- name: Application
- name: Applications
description: Operations about applications
- name: Avatar
- name: Broadcast Messages
description: Operations about broadcast_messages
- name: Bulk Imports
description: Operations about bulk_imports
- name: Groups
- name: Metadata
description: Operations related to metadata of the GitLab instance
- name: Projects
description: Operations related to projects
- name: Version
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-22T14:13:35Z
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-22T14:13:35Z
access_level: 20
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/repository/merged_branches:
delete:
tags:
- Projects
description: Delete all merged branches
operationId: deleteApiV4ProjectsIdRepositoryMergedBranches
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
responses:
'202':
description: 202 Accepted
content: {}
'404':
description: 404 Project Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/repository/branches/{branch}:
get:
tags:
- Projects
description: Get a single repository branch
operationId: getApiV4ProjectsIdRepositoryBranchesBranch
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: branch
in: path
required: true
schema:
type: integer
format: int32
example: 42
responses:
'200':
description: Get a single repository branch
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Branch'
'404':
description: Branch Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- Projects
description: Delete a branch
operationId: deleteApiV4ProjectsIdRepositoryBranchesBranch
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: branch
in: path
description: The name of the branch
required: true
schema:
type: string
example: main
responses:
'204':
description: Delete a branch
content: {}
'404':
description: Branch Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
head:
tags:
- Projects
description: Check if a branch exists
operationId: headApiV4ProjectsIdRepositoryBranchesBranch
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
- name: branch
in: path
description: The name of the branch
required: true
schema:
type: string
responses:
'204':
description: No Content
content: {}
'404':
description: Not Found
content: {}
/api/v4/projects/{id}/repository/branches:
get:
tags:
- Projects
description: Get a project repository branches
operationId: getApiV4ProjectsIdRepositoryBranches
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
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: search
in: query
description: Return list of branches matching the search criteria
schema:
type: string
example: example_value
- name: regex
in: query
description: Return list of branches matching the regex
schema:
type: string
example: example_value
- name: sort
in: query
description: Return list of branches sorted by the given field
schema:
type: string
enum:
- name_asc
- updated_asc
- updated_desc
example: name_asc
- name: page_token
in: query
description: Name of branch to start the pagination from
schema:
type: string
example: glpat-example-token
responses:
'200':
description: Get a project repository branches
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/API_Entities_Branch'
'404':
description: 404 Project Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Projects
description: Create branch
operationId: postApiV4ProjectsIdRepositoryBranches
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: branch
in: query
description: The name of the branch
required: true
schema:
type: string
example: main
- name: ref
in: query
description: Create branch from commit sha or existing branch
required: true
schema:
type: string
example: main
responses:
'201':
description: Create branch
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Branch'
'400':
description: Failed to create branch
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/repository/branches/{branch}/unprotect:
put:
tags:
- Projects
description: Unprotect a single branch
operationId: putApiV4ProjectsIdRepositoryBranchesBranchUnprotect
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: branch
in: path
description: The name of the branch
required: true
schema:
type: string
example: main
responses:
'200':
description: Unprotect a single branch
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Branch'
'404':
description: 404 Project Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/repository/branches/{branch}/protect:
put:
tags:
- Projects
description: Protect a single branch
operationId: putApiV4ProjectsIdRepositoryBranchesBranchProtect
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: branch
in: path
description: The name of the branch
required: true
schema:
type: string
example: main
requestBody:
content:
application/json:
schema:
properties:
developers_can_push:
type: boolean
description: Flag if developers can push to that branch
developers_can_merge:
type: boolean
description: Flag if developers can merge to that branch
responses:
'200':
description: Protect a single branch
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Branch'
'404':
description: 404 Branch Not Found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/badges/{badge_id}:
get:
tags:
- Projects
summary: GitLab Gets a Badge of a Project.
description: This feature was introduced in GitLab 10.6.
operationId: getApiV4ProjectsIdBadgesBadgeId
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Badge'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
tags:
- Projects
summary: GitLab Updates a Badge of a Project.
description: This feature was introduced in GitLab 10.6.
operationId: putApiV4ProjectsIdBadgesBadgeId
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Badge'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- Projects
summary: GitLab Removes a Badge from the Project.
description: This feature was introduced in GitLab 10.6.
operationId: deleteApiV4ProjectsIdBadgesBadgeId
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/badges:
get:
tags:
- Projects
summary: GitLab Gets a List of Project Badges Viewable by the Authenticated User.
description: This feature was introduced in GitLab 10.6.
operationId: getApiV4ProjectsIdBadges
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project 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:
- Projects
summary: GitLab Adds a Badge to a Project.
description: This feature was introduced in GitLab 10.6.
operationId: postApiV4ProjectsIdBadges
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Badge'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/badges/render:
get:
tags:
- Projects
summary: GitLab Preview a Badge from a Project.
description: This feature was introduced in GitLab 10.6.
operationId: getApiV4ProjectsIdBadgesRender
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_BasicBadgeDetails'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/access_requests/{user_id}:
delete:
tags:
- Projects
summary: GitLab Denies an Access Request for the Given User.
description: This feature was introduced in GitLab 8.11.
operationId: deleteApiV4ProjectsIdAccessRequestsUserId
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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/projects/{id}/access_requests/{user_id}/approve:
put:
tags:
- Projects
summary: GitLab Approves an Access Request for the Given User.
description: This feature was introduced in GitLab 8.11.
operationId: putApiV4ProjectsIdAccessRequestsUserIdApprove
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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-22T14:13:35Z
access_level: 20
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/access_requests:
get:
tags:
- Projects
summary: GitLab Gets a List of Access Requests for a Project.
description: This feature was introduced in GitLab 8.11.
operationId: getApiV4ProjectsIdAccessRequests
parameters:
- name: id
in: path
description: >-
The ID or URL-encoded path of the project 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 project.
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_AccessRequester'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Projects
summary: GitLab Requests Access for the Authenticated User to a Project.
description: This feature was introduced in GitLab 8.11.
operationId: postApiV4ProjectsIdAccessRequests
parameters:
- name: id
in: path
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab/refs/heads/main/openapi/gitlab-openapi-original.yml