---
title: "Create a merge request"
method: POST
path: "/api/v4/projects/{id}/merge_requests"
tags: ["merge_requests"]
---

# Create a merge request

`POST /api/v4/projects/{id}/merge_requests`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/projects/{id}/merge_requests`
- Auth: none declared

Creates a merge request for a project.

## Path parameters

- `id` string, required

## Request body

- PostApiV4ProjectsIdMergeRequests: Create a merge request
  - `title` string, required: The title of the merge request.
  - `source_branch` string, required: The source branch.
  - `target_branch` string, required: The target branch.
  - `target_project_id` integer: The target project of the merge request defaults to the :id of the project.
  - `assignee_id` integer: Assignee user ID.
  - `assignee_ids` integer[]: The IDs of the users to assign the merge request to, as a comma-separated list. Set to 0 or provide an empty value to unassign all assignees.
  - `reviewer_ids` integer[]: The IDs of the users to review the merge request, as a comma-separated list. Set to 0 or provide an empty value to unassign all reviewers.
  - `description` string: Description of the merge request. Limited to 1,048,576 characters.
  - `labels` string[]: Comma-separated label names for a merge request. Set to an empty string to unassign all labels.
  - `add_labels` string[]: Comma-separated label names to add to a merge request.
  - `remove_labels` string[]: Comma-separated label names to remove from a merge request.
  - `milestone_id` integer: The global ID of a milestone to assign the merge request to.
  - `milestone` string: The title of a project or ancestor-group milestone to assign the merge request to. Mutually exclusive with `milestone_id`.
  - `remove_source_branch` boolean: Flag indicating if a merge request should remove the source branch when merging.
  - `allow_collaboration` boolean: Allow commits from members who can merge to the target branch.
  - `allow_maintainer_to_push` boolean: [deprecated] See allow_collaboration
  - `squash` boolean: Squash commits into a single commit when merging.
  - `merge_after` string, date-time: Date after which the merge request can be merged.
  - `approvals_before_merge` integer: Number of approvals required before this can be merged

## Response `201`

Create a merge request

- APIEntitiesMergeRequest: API_Entities_MergeRequest model
  - `id` integer, required
  - `iid` integer, required
  - `project_id` integer, required
  - `title` string, required
  - `description` string, required
  - `state` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `merged_by` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `merge_user` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `merged_at` string, date-time, required
  - `closed_by` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `closed_at` string, date-time, required
  - `title_html` string
  - `description_html` string
  - `target_branch` string, required
  - `source_branch` string, required
  - `user_notes_count` integer, required
  - `upvotes` integer, required
  - `downvotes` integer, required
  - `author` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `assignees` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `assignee` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `reviewers` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `source_project_id` integer, required
  - `target_project_id` integer, required
  - `labels` string[], required
  - `draft` boolean, required
  - `imported` boolean, required
  - `imported_from` string, required
  - `work_in_progress` boolean, required
  - `milestone` APIEntitiesMilestone, required
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer
    - `group_id` string
    - `title` string, required
    - `description` string, required
    - `state` string, required
    - `created_at` string, required
    - `updated_at` string, required
    - `due_date` string, required
    - `start_date` string, required
    - `expired` boolean, required
    - `web_url` string, required
  - `merge_when_pipeline_succeeds` boolean, required
  - `merge_status` string, required
  - `detailed_merge_status` string, required
  - `merge_after` string, date-time, required
  - `sha` string, required
  - `merge_commit_sha` string, required
  - `squash_commit_sha` string, required
  - `discussion_locked` boolean, required
  - `should_remove_source_branch` boolean, required
  - `force_remove_source_branch` boolean, required
  - `prepared_at` string, date-time, required
  - `allow_collaboration` boolean
  - `allow_maintainer_to_push` boolean
  - `reference` string, required
  - `references` APIEntitiesIssuableReferences, required
    - `short` string, required
    - `relative` string, required
    - `full` string, required
  - `web_url` string, required
  - `time_stats` APIEntitiesIssuableTimeStats, required: API_Entities_IssuableTimeStats model
    - `time_estimate` integer, required
    - `total_time_spent` integer, required
    - `human_time_estimate` string, required
    - `human_total_time_spent` string, required
  - `squash` boolean, required
  - `squash_on_merge` boolean, required
  - `task_completion_status` APIEntitiesTaskCompletionStatus, required
    - `count` integer, required
    - `completed_count` integer, required
  - `has_conflicts` boolean, required
  - `blocking_discussions_resolved` boolean, required
  - `approvals_before_merge` integer, required
  - `subscribed` boolean
  - `changes_count` string, required
  - `latest_build_started_at` string, date-time
  - `latest_build_finished_at` string, date-time
  - `first_deployed_to_production_at` string, date-time
  - `pipeline` APIEntitiesCiPipelineBasic: API_Entities_Ci_PipelineBasic model
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer, required
    - `sha` string, required
    - `ref` string, required
    - `status` string, required
    - `source` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `web_url` string, required
  - `head_pipeline` APIEntitiesCiPipeline: API_Entities_Ci_Pipeline model
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer, required
    - `sha` string, required
    - `ref` string, required
    - `status` string, required
    - `source` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `web_url` string, required
    - `before_sha` string, required
    - `tag` boolean, required
    - `yaml_errors` string, required
    - `user` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `started_at` string, date-time, required
    - `finished_at` string, date-time, required
    - `committed_at` string, date-time, required
    - `duration` integer, required: Time spent running in seconds
    - `queued_duration` integer, required: Time spent enqueued in seconds
    - `coverage` number, float, required
    - `detailed_status` DetailedStatusEntity, required
      - `icon` string, required
      - `text` string, required
      - `label` string, required
      - `group` string, required
      - `tooltip` string, required
      - `has_details` boolean, required
      - `details_path` string, required
      - `illustration` object, required
      - `favicon` string, required
      - `action` object
        - `icon` string, required
        - `title` string, required
        - `path` string, required
        - `method` string, required
        - `button_title` string, required
        - `confirmation_message` string, required
    - `archived` boolean, required
  - `diff_refs` APIEntitiesDiffRefs, required
    - `base_sha` string, required
    - `head_sha` string, required
    - `start_sha` string, required
  - `merge_error` string, required
  - `rebase_in_progress` boolean
  - `diverged_commits_count` integer
  - `first_contribution` boolean
  - `user` object, required
    - `can_merge` boolean, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found
- `409`: Conflict
- `422`: Unprocessable entity

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)