Operations related to merge requests
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/gitlab-ci-merge-requests-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: GitLab access_requests Merge Requests API
version: v4
description: Operations related to access requests
servers:
- url: https://gitlab.com
tags:
- name: merge_requests
description: Operations related to merge requests
paths:
/api/v4/groups/{id}/merge_requests:
get:
summary: List group merge requests
description: Get all merge requests for this group and its subgroups.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the group owned by the authenticated user.
required: true
schema:
type: string
- in: query
name: author_id
description: Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.
required: false
schema:
type: integer
format: int32
- in: query
name: author_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
required: false
schema:
type: string
- in: query
name: assignee_id
description: Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.
required: false
schema:
type: integer
format: int32
- in: query
name: assignee_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
required: false
schema:
type: array
items:
type: string
- in: query
name: reviewer_username
description: Returns merge requests which have the user as a reviewer with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. Introduced in GitLab 13.8.
required: false
schema:
type: string
- in: query
name: labels
description: Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive.
required: false
schema:
type: array
items:
type: string
- in: query
name: milestone
description: Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.
required: false
schema:
type: string
- in: query
name: my_reaction_emoji
description: Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction.
required: false
schema:
type: string
- in: query
name: reviewer_id
description: Returns merge requests which have the user as a reviewer with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`.
required: false
schema:
type: integer
format: int32
- in: query
name: state
description: Returns `all` merge requests or just those that are `opened`, `closed`, `locked`, or `merged`.
required: false
schema:
type: string
enum:
- opened
- closed
- locked
- merged
- all
default: all
- in: query
name: order_by
description: Returns merge requests ordered by `created_at`, `label_priority`, `milestone_due`, `popularity`, `priority`, `title`, `updated_at` or `merged_at` fields. Introduced in GitLab 14.8.
required: false
schema:
type: string
enum:
- created_at
- label_priority
- milestone_due
- popularity
- priority
- title
- updated_at
- merged_at
default: created_at
- in: query
name: sort
description: Returns merge requests sorted in `asc` or `desc` order.
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- in: query
name: with_labels_details
description: 'If `true`, response returns more details for each label in labels field: `:name`,`:color`, `:description`, `:description_html`, `:text_color`'
required: false
schema:
type: boolean
default: false
- in: query
name: with_merge_status_recheck
description: If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Introduced in GitLab 13.0.
required: false
schema:
type: boolean
default: false
- in: query
name: created_after
description: Returns merge requests created on or after the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: created_before
description: Returns merge requests created on or before the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: updated_after
description: Returns merge requests updated on or after the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: updated_before
description: Returns merge requests updated on or before the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: view
description: If simple, returns the `iid`, URL, title, description, and basic state of merge request
required: false
schema:
type: string
enum:
- simple
- in: query
name: scope
description: 'Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, `reviews_for_me` or `all`'
required: false
schema:
type: string
enum:
- created-by-me
- assigned-to-me
- created_by_me
- assigned_to_me
- reviews_for_me
- all
- in: query
name: source_branch
description: Returns merge requests with the given source branch
required: false
schema:
type: string
- in: query
name: source_project_id
description: Returns merge requests with the given source project id
required: false
schema:
type: integer
format: int32
- in: query
name: target_branch
description: Returns merge requests with the given target branch
required: false
schema:
type: string
- in: query
name: search
description: Search merge requests against their `title` and `description`.
required: false
schema:
type: string
- in: query
name: in
description: Modify the scope of the search attribute. `title`, `description`, or a string joining them with comma.
required: false
example: title,description
schema:
type: string
- in: query
name: wip
description: Deprecated. Use `draft` instead. Filter merge requests against their `wip` status. `yes` to return only draft merge requests, `no` to return non-draft merge requests.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- in: query
name: draft
description: Filter merge requests against their `draft` status. `true` to return only draft merge requests, `false` to return non-draft merge requests.
required: false
schema:
type: boolean
- in: query
name: not[author_id]
description: '`<Negated>` Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.'
required: false
schema:
type: integer
format: int32
- in: query
name: not[author_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
required: false
schema:
type: string
- in: query
name: not[assignee_id]
description: '`<Negated>` Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.'
required: false
schema:
type: integer
format: int32
- in: query
name: not[assignee_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
required: false
schema:
type: array
items:
type: string
- in: query
name: not[reviewer_username]
description: '`<Negated>` Returns merge requests which have the user as a reviewer with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. Introduced in GitLab 13.8.'
required: false
schema:
type: string
- in: query
name: not[labels]
description: '`<Negated>` Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive.'
required: false
schema:
type: array
items:
type: string
- in: query
name: not[milestone]
description: '`<Negated>` Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.'
required: false
schema:
type: string
- in: query
name: not[my_reaction_emoji]
description: '`<Negated>` Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction.'
required: false
schema:
type: string
- in: query
name: not[reviewer_id]
description: '`<Negated>` Returns merge requests which have the user as a reviewer with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`.'
required: false
schema:
type: integer
format: int32
- in: query
name: deployed_before
description: Returns merge requests deployed before the given date/time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
- in: query
name: deployed_after
description: Returns merge requests deployed after the given date/time. Expected in ISO 8601 format
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
- in: query
name: environment
description: Returns merge requests deployed to the given environment
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
- in: query
name: approved
description: Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- in: query
name: merge_user_id
description: Returns merge requests which have been merged by the user with the given user `id`. Mutually exclusive with `merge_user_username`.
required: false
schema:
type: integer
format: int32
- in: query
name: merge_user_username
description: Returns merge requests which have been merged by the user with the given `username`. Mutually exclusive with `merge_user_id`.
required: false
schema:
type: string
- in: query
name: approver_ids
description: Return merge requests which have specified the users with the given IDs as an individual approver
required: false
schema:
type: string
- in: query
name: approved_by_ids
description: Return merge requests which have been approved by the specified users with the given IDs
required: false
schema:
type: string
- in: query
name: approved_by_usernames
description: "Return merge requests which have been approved by the specified users with the given\n usernames"
required: false
schema:
type: string
- in: query
name: page
description: Current page number
required: false
example: 1
schema:
type: integer
format: int32
default: 1
- in: query
name: per_page
description: Number of items per page
required: false
example: 20
schema:
type: integer
format: int32
default: 20
- in: query
name: non_archived
description: Returns merge requests from non archived projects only.
required: false
schema:
type: boolean
default: true
responses:
'200':
description: List group merge requests
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/API_Entities_MergeRequestBasic'
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- merge_requests
operationId: getApiV4GroupsIdMergeRequests
/api/v4/projects/{id}/create_ci_config:
post:
summary: Create merge request for missing ci config in project
description: Creates a merge request to add missing CI configuration
parameters:
- in: path
name: id
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Create merge request for missing ci config in project
tags:
- merge_requests
operationId: postApiV4ProjectsIdCreateCiConfig
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/time_estimate:
post:
summary: Set a time estimate for a merge_request
description: Sets an estimated time of work for this merge_request.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Set a time estimate for a merge_request
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'400':
description: Bad request
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidTimeEstimate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postApiV4ProjectsIdMergeRequestsMergeRequestIidTimeEstimate'
required: true
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/reset_time_estimate:
post:
summary: Reset the time estimate for a project merge_request
description: Resets the estimated time for this merge_request to 0 seconds.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Reset the time estimate for a project merge_request
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidResetTimeEstimate
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/add_spent_time:
post:
summary: Add spent time for a merge_request
description: Adds spent time for this merge_request.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Add spent time for a merge_request
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidAddSpentTime
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postApiV4ProjectsIdMergeRequestsMergeRequestIidAddSpentTime'
required: true
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/reset_spent_time:
post:
summary: Reset spent time for a merge_request
description: Resets the total spent time for this merge_request to 0 seconds.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: path
name: merge_request_iid
description: The internal ID of the merge_request
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Reset spent time for a merge_request
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidResetSpentTime
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/time_stats:
get:
summary: Get time tracking stats
description: Get time tracking stats
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: path
name: merge_request_iid
description: The internal ID of the merge_request
required: true
schema:
type: integer
format: int32
responses:
'200':
description: Get time tracking stats
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: getApiV4ProjectsIdMergeRequestsMergeRequestIidTimeStats
/api/v4/projects/{id}/merge_requests:
get:
summary: List project merge requests
description: Get all merge requests for this project.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
required: true
schema:
type: string
- in: query
name: author_id
description: Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.
required: false
schema:
type: integer
format: int32
- in: query
name: author_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
required: false
schema:
type: string
- in: query
name: assignee_id
description: Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.
required: false
schema:
type: integer
format: int32
- in: query
name: assignee_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
required: false
schema:
type: array
items:
type: string
- in: query
name: reviewer_username
description: Returns merge requests which have the user as a reviewer with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. Introduced in GitLab 13.8.
required: false
schema:
type: string
- in: query
name: labels
description: Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive.
required: false
schema:
type: array
items:
type: string
- in: query
name: milestone
description: Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.
required: false
schema:
type: string
- in: query
name: my_reaction_emoji
description: Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction.
required: false
schema:
type: string
- in: query
name: reviewer_id
description: Returns merge requests which have the user as a reviewer with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`.
required: false
schema:
type: integer
format: int32
- in: query
name: state
description: Returns `all` merge requests or just those that are `opened`, `closed`, `locked`, or `merged`.
required: false
schema:
type: string
enum:
- opened
- closed
- locked
- merged
- all
default: all
- in: query
name: order_by
description: Returns merge requests ordered by `created_at`, `label_priority`, `milestone_due`, `popularity`, `priority`, `title`, `updated_at` or `merged_at` fields. Introduced in GitLab 14.8.
required: false
schema:
type: string
enum:
- created_at
- label_priority
- milestone_due
- popularity
- priority
- title
- updated_at
- merged_at
default: created_at
- in: query
name: sort
description: Returns merge requests sorted in `asc` or `desc` order.
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- in: query
name: with_labels_details
description: 'If `true`, response returns more details for each label in labels field: `:name`,`:color`, `:description`, `:description_html`, `:text_color`'
required: false
schema:
type: boolean
default: false
- in: query
name: with_merge_status_recheck
description: If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Introduced in GitLab 13.0.
required: false
schema:
type: boolean
default: false
- in: query
name: created_after
description: Returns merge requests created on or after the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: created_before
description: Returns merge requests created on or before the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: updated_after
description: Returns merge requests updated on or after the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: updated_before
description: Returns merge requests updated on or before the given time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
type: string
format: date-time
- in: query
name: view
description: If simple, returns the `iid`, URL, title, description, and basic state of merge request
required: false
schema:
type: string
enum:
- simple
- in: query
name: scope
description: 'Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, `reviews_for_me` or `all`'
required: false
schema:
type: string
enum:
- created-by-me
- assigned-to-me
- created_by_me
- assigned_to_me
- reviews_for_me
- all
- in: query
name: source_branch
description: Returns merge requests with the given source branch
required: false
schema:
type: string
- in: query
name: source_project_id
description: Returns merge requests with the given source project id
required: false
schema:
type: integer
format: int32
- in: query
name: target_branch
description: Returns merge requests with the given target branch
required: false
schema:
type: string
- in: query
name: search
description: Search merge requests against their `title` and `description`.
required: false
schema:
type: string
- in: query
name: in
description: Modify the scope of the search attribute. `title`, `description`, or a string joining them with comma.
required: false
example: title,description
schema:
type: string
- in: query
name: wip
description: Deprecated. Use `draft` instead. Filter merge requests against their `wip` status. `yes` to return only draft merge requests, `no` to return non-draft merge requests.
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- in: query
name: draft
description: Filter merge requests against their `draft` status. `true` to return only draft merge requests, `false` to return non-draft merge requests.
required: false
schema:
type: boolean
- in: query
name: not[author_id]
description: '`<Negated>` Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.'
required: false
schema:
type: integer
format: int32
- in: query
name: not[author_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
required: false
schema:
type: string
- in: query
name: not[assignee_id]
description: '`<Negated>` Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.'
required: false
schema:
type: integer
format: int32
- in: query
name: not[assignee_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
required: false
schema:
type: array
items:
type: string
- in: query
name: not[reviewer_username]
description: '`<Negated>` Returns merge requests which have the user as a reviewer with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. Introduced in GitLab 13.8.'
required: false
schema:
type: string
- in: query
name: not[labels]
description: '`<Negated>` Returns merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive.'
required: false
schema:
type: array
items:
type: string
- in: query
name: not[milestone]
description: '`<Negated>` Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.'
required: false
schema:
type: string
- in: query
name: not[my_reaction_emoji]
description: '`<Negated>` Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction.'
required: false
schema:
type: string
- in: query
name: not[reviewer_id]
description: '`<Negated>` Returns merge requests which have the user as a reviewer with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`.'
required: false
schema:
type: integer
format: int32
- in: query
name: deployed_before
description: Returns merge requests deployed before the given date/time. Expected in ISO 8601 format.
required: false
example: '2019-03-15T08:00:00Z'
schema:
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-merge-requests-api-openapi.yml