The GitLab Projects API provides programmatic access to GitLab projects, enabling you to create, list, update, and delete projects. It supports managing project settings, members, forks, stars, and other project-level resources across GitLab.com and self-managed instances.
openapi: 3.0.1
info:
title: 'GitLab api/v4/projects'
version: v4
description: Needs description.
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: Projects
paths:
/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:35.000Z'
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
description: >-
The ID or URL-encoded path of the project 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:35.000Z'
access_level: 20
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images/{metric_image_id}:
put:
tags:
- Projects
description: Update a metric image for an alert
operationId: putApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImagesMetricImageId
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: alert_iid
in: path
description: The IID of the Alert
required: true
schema:
type: integer
format: int32
example: 42
- name: metric_image_id
in: path
description: The ID of metric image
required: true
schema:
type: integer
format: int32
example: 42
requestBody:
content:
multipart/form-data:
schema:
properties:
url:
type: string
description: The url to view more metric info
url_text:
type: string
description: A description of the image or URL
responses:
'200':
description: Update a metric image for an alert
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_MetricImage'
'403':
description: Forbidden
content: {}
'422':
description: Unprocessable entity
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- Projects
description: Remove a metric image for an alert
operationId: >-
deleteApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImagesMetricImageId
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: alert_iid
in: path
description: The IID of the Alert
required: true
schema:
type: integer
format: int32
example: 42
- name: metric_image_id
in: path
description: The ID of metric image
required: true
schema:
type: integer
format: int32
example: 42
responses:
'204':
description: Remove a metric image for an alert
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_MetricImage'
'403':
description: Forbidden
content: {}
'422':
description: Unprocessable entity
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images:
get:
tags:
- Projects
description: Metric Images for alert
operationId: getApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImages
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: alert_iid
in: path
description: The IID of the Alert
required: true
schema:
type: integer
format: int32
example: 42
responses:
'200':
description: Metric Images for alert
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/API_Entities_MetricImage'
'404':
description: Not found
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Projects
description: Upload a metric image for an alert
operationId: postApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImages
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: alert_iid
in: path
description: The IID of the Alert
required: true
schema:
type: integer
format: int32
example: 42
requestBody:
content:
multipart/form-data:
schema:
required:
- file
properties:
file:
type: string
description: The image file to be uploaded
format: binary
url:
type: string
description: The url to view more metric info
url_text:
type: string
description: A description of the image or URL
required: true
responses:
'200':
description: Upload a metric image for an alert
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_MetricImage'
'403':
description: Forbidden
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images/authorize:
post:
tags:
- Projects
description: Workhorse authorize metric image file upload
operationId: postApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImagesAuthorize
parameters:
- name: id
in: path
description: The ID or URL-encoded path of the project
required: true
schema:
type: string
example: '123456'
- name: alert_iid
in: path
description: The IID of the Alert
required: true
schema:
type: integer
format: int32
example: 42
responses:
'200':
description: Workhorse authorize metric image file upload
content: {}
'403':
description: Forbidden
content: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/jobs:
get:
tags:
- Projects
summary: GitLab List Jobs for a Project
operationId: listProjectJobs
parameters:
- name: id
in: path
required: true
description: The ID of the project
schema:
type: integer
example: 42
- name: scope
in: query
required: false
description: Return all jobs with the specified statuses
schema:
type: array
items:
type: string
responses:
'200':
description: An array of jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/API_Entities_Job'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/jobs/{job_id}:
get:
tags:
- Projects
summary: GitLab Get a Single Job by ID
operationId: getSingleJob
parameters:
- name: id
in: path
required: true
description: The ID of the project
schema:
type: integer
example: 42
- name: job_id
in: path
required: true
description: The ID of the job
schema:
type: integer
example: 42
responses:
'200':
description: A single job object
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Job'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v4/projects/{id}/jobs/{job_id}/play:
post:
tags:
- Projects
summary: GitLab Run a Manual Job
operationId: triggerManualJob
parameters:
- name: id
in: path
required: true
description: The ID of the project
schema:
type: integer
example: 42
- name: job_id
in: path
required: true
description: The ID of the manual job to run
schema:
type: integer
example: 42
- name: job_variables_attributes
in: query
required: false
description: An array containing the custom variables available to the job
schema:
type: array
items:
type: string
responses:
'200':
description: Job started successfully
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
API_Entities_Branch:
type: object
properties:
name:
type: string
example: master
commit:
$ref: '#/components/schemas/API_Entities_Commit'
merged:
type: boolean
example: true
protected:
type: boolean
example: true
developers_can_push:
type: boolean
example: true
developers_can_merge:
type: boolean
example: true
can_push:
type: boolean
example: true
default:
type: boolean
example: true
web_url:
type: string
example: https://gitlab.example.com/Commit921/the-dude/-/tree/master
description: API_Entities_Branch 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_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: [email protected]
requested_at:
type: string
example: '2026-04-17T12:00:00Z'
description: API_Entities_AccessRequester model
API_Entities_MetricImage:
type: object
properties:
id:
type: integer
format: int32
example: 23
created_a
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab/refs/heads/main/openapi/gitlab-api-v4-projects-openapi-original.yml