Suggest Changes API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

When you review code, suggestions provide a way to propose specific changes that can be directly applied. For more information, see Suggest changes.

You can programmatically create and apply code suggestions in merge request discussions with this API. Every API call to suggestions must be authenticated.

Create a suggestion

To create a suggestion through the API, use the Discussions API to create a new thread in the merge request diff. The format for suggestions is:

Markdown Copy to clipboard 
```suggestion:-3+0
example text
```

Apply a suggestion

Applies a suggested patch in a merge request. Users must have at least the Developer role to perform such action.

Copy to clipboard 
PUT /suggestions/:id/apply
AttributeTypeRequiredDescription
idintegeryesThe ID of a suggestion
commit_messagestringnoA custom commit message to use instead of the default generated message or the project’s default message
Shell Copy to clipboard 
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/suggestions/5/apply"

Example response:

JSON Copy to clipboard 
{
  "id": 5,
  "from_line": 10,
  "to_line": 10,
  "applicable": true,
  "applied": false,
  "from_content": "This is an example\n",
  "to_content": "This is an example\n"
}

Apply multiple suggestions

Copy to clipboard 
PUT /suggestions/batch_apply
AttributeTypeRequiredDescription
idsintegeryesThe IDs of suggestions
commit_messagestringnoA custom commit message to use instead of the default generated message or the project’s default message
Shell Copy to clipboard 
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"ids": [5, 6]}' \
  --url "https://gitlab.example.com/api/v4/suggestions/batch_apply"

Example response:

JSON Copy to clipboard 
[
  {
    "id": 5,
    "from_line": 10,
    "to_line": 10,
    "applicable": true,
    "applied": false,
    "from_content": "This is an example\n",
    "to_content": "This is an example\n"
  }
  {
    "id": 6,
    "from_line": 19
    "to_line": 19,
    "applicable": true,
    "applied": false,
    "from_content": "This is another example\n",
    "to_content": "This is another example\n"
  }
 ]