API reference

This page provides documentation for the API endpoints provided by the application.

Hooks

Process project webhook

Perform action based on project webhook event type:

push: update project based on changes to dependabot.yml file
merge_request: perform various actions based on merge request status
note: process dependabot comment commands
pipeline: accept and auto merge merge request on successful pipeline
issue: update internal status of vulnerability on issue close See https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html for more details

txt

POST /api/v2/hooks

Attribute	In	Type	Required	Description
X-Gitlab-Token	header	string	false	Webhook secret token. Required if SETTINGS__GITLAB_AUTH_TOKEN is set
object_kind	body	string	true	Webhook event type
project	body	object	true
commits	body	array	false
merge_request	body	object	false
object_attributes	body	object	false

Responses

Code	Description
201	Successful response

Code	Description
400	Event not supported

Code	Description
401	Invalid gitlab authentication token

Process system hook

Create or update project based on received system webhook event

txt

POST /api/v2/hooks/system/project_registration

Attribute	In	Type	Required	Description
event_name	body	string	true	Event name
path_with_namespace	body	string	false	Project full path
old_path_with_namespace	body	string	false	Project full path before renaming

Responses

Code Description

201

Successful response

json

{
  "id": 1,
  "name": "foo/bar",
  "forked_from_id": 2,
  "forked_from_name": null,
  "webhook_id": 3,
  "web_url": "https://gitlab.com/foo/bar",
  "configuration": {
    "updates": [
      {
        "package_manager": "docker",
        "package_ecosystem": "docker",
        "directory": "/docker",
        "registries": "*",
        "open_merge_requests_limit": 5,
        "open_security_merge_requests_limit": 10,
        "updater_options": {},
        "reject_external_code": true,
        "branch_name_prefix": "dependabot",
        "branch_name_separator": "-",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [],
        "cron": "23 16 * * * UTC",
        "rebase_strategy": {
          "strategy": "auto"
        },
        "vulnerability_alerts": {
          "enabled": true,
          "confidential": true
        }
      }
    ],
    "registries": {
      "docker-gitlab": {
        "type": "docker-registry",
        "url": "registry.gitlab.com",
        "username": "dependabot-bot"
      }
    },
    "forked": false
  }
}

Code	Description
204	Skipped, event not supported\|Skipped, does not match allowed namespace pattern

Projects

Get all projects

Return array of all projects registered for dependency updates

txt

GET /api/v2/projects

Attribute	In	Type	Required	Description
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.

Responses

Code Description

200

Successful response

json

[
  {
    "id": 1,
    "name": "foo/bar",
    "forked_from_id": 2,
    "forked_from_name": null,
    "webhook_id": 3,
    "web_url": "https://gitlab.com/foo/bar",
    "configuration": {
      "updates": [
        {
          "package_manager": "docker",
          "package_ecosystem": "docker",
          "directory": "/docker",
          "registries": "*",
          "open_merge_requests_limit": 5,
          "open_security_merge_requests_limit": 10,
          "updater_options": {},
          "reject_external_code": true,
          "branch_name_prefix": "dependabot",
          "branch_name_separator": "-",
          "allow": [
            {
              "dependency_type": "direct"
            }
          ],
          "ignore": [],
          "cron": "23 16 * * * UTC",
          "rebase_strategy": {
            "strategy": "auto"
          },
          "vulnerability_alerts": {
            "enabled": true,
            "confidential": true
          }
        }
      ],
      "registries": {
        "docker-gitlab": {
          "type": "docker-registry",
          "url": "registry.gitlab.com",
          "username": "dependabot-bot"
        }
      },
      "forked": false
    }
  }
]

Add project

txt

POST /api/v2/projects

Attribute	In	Type	Required	Description
project_name	body	string	true	Project full path
gitlab_access_token	body	string	false	Project specific access token

Responses

Code Description

201

Successful response

json

{
  "id": 1,
  "name": "foo/bar",
  "forked_from_id": 2,
  "forked_from_name": null,
  "webhook_id": 3,
  "web_url": "https://gitlab.com/foo/bar",
  "configuration": {
    "updates": [
      {
        "package_manager": "docker",
        "package_ecosystem": "docker",
        "directory": "/docker",
        "registries": "*",
        "open_merge_requests_limit": 5,
        "open_security_merge_requests_limit": 10,
        "updater_options": {},
        "reject_external_code": true,
        "branch_name_prefix": "dependabot",
        "branch_name_separator": "-",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [],
        "cron": "23 16 * * * UTC",
        "rebase_strategy": {
          "strategy": "auto"
        },
        "vulnerability_alerts": {
          "enabled": true,
          "confidential": true
        }
      }
    ],
    "registries": {
      "docker-gitlab": {
        "type": "docker-registry",
        "url": "registry.gitlab.com",
        "username": "dependabot-bot"
      }
    },
    "forked": false
  }
}

Code	Description
409	Project already exists

Get single project

Return single project

txt

GET /api/v2/projects/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path

Responses

Code Description

200

Successful response

json

{
  "id": 1,
  "name": "foo/bar",
  "forked_from_id": 2,
  "forked_from_name": null,
  "webhook_id": 3,
  "web_url": "https://gitlab.com/foo/bar",
  "configuration": {
    "updates": [
      {
        "package_manager": "docker",
        "package_ecosystem": "docker",
        "directory": "/docker",
        "registries": "*",
        "open_merge_requests_limit": 5,
        "open_security_merge_requests_limit": 10,
        "updater_options": {},
        "reject_external_code": true,
        "branch_name_prefix": "dependabot",
        "branch_name_separator": "-",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [],
        "cron": "23 16 * * * UTC",
        "rebase_strategy": {
          "strategy": "auto"
        },
        "vulnerability_alerts": {
          "enabled": true,
          "confidential": true
        }
      }
    ],
    "registries": {
      "docker-gitlab": {
        "type": "docker-registry",
        "url": "registry.gitlab.com",
        "username": "dependabot-bot"
      }
    },
    "forked": false
  }
}

Code	Description
404	Project not found

Update project

Update project attributes

txt

PUT /api/v2/projects/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path
name	body	string		Project name
forked_from_id	body	integer		Forked from project id
forked_from_name	body	string		Forked from project name
webhook_id	body	integer		Webhook id
web_url	body	string		Web url
configuration	body	object

Responses

Code Description

200

Successful response

json

{
  "id": 1,
  "name": "foo/bar",
  "forked_from_id": 2,
  "forked_from_name": null,
  "webhook_id": 3,
  "web_url": "https://gitlab.com/foo/bar",
  "configuration": {
    "updates": [
      {
        "package_manager": "docker",
        "package_ecosystem": "docker",
        "directory": "/docker",
        "registries": "*",
        "open_merge_requests_limit": 5,
        "open_security_merge_requests_limit": 10,
        "updater_options": {},
        "reject_external_code": true,
        "branch_name_prefix": "dependabot",
        "branch_name_separator": "-",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [],
        "cron": "23 16 * * * UTC",
        "rebase_strategy": {
          "strategy": "auto"
        },
        "vulnerability_alerts": {
          "enabled": true,
          "confidential": true
        }
      }
    ],
    "registries": {
      "docker-gitlab": {
        "type": "docker-registry",
        "url": "registry.gitlab.com",
        "username": "dependabot-bot"
      }
    },
    "forked": false
  }
}

Code	Description
404	Project not found

Remove project

Remove project from database

txt

DELETE /api/v2/projects/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path

Responses

Code	Description
204	Removed project

Code	Description
404	Project not found

Get all merge requests

Return array of merge requests for a project

txt

GET /api/v2/projects/{id}/merge_requests

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
state	query	string	false	Filter by state
package_ecosystem	query	string	false	Filter by package ecosystem
main_dependency	query	string	false	Filter by main dependency

Responses

Code Description

200

Successful response

json

[
  {
    "id": 1,
    "iid": 1,
    "package_ecosystem": "npm_and_yarn",
    "directory": "/",
    "state": "opened",
    "auto_merge": false,
    "squash": false,
    "update_from": "1.0.0",
    "update_to": "1.0.1",
    "main_dependency": "lodash",
    "branch": "dependabot/npm_and_yarn/lodash-1.0.1",
    "target_branch": "main",
    "target_project_id": null,
    "commit_message": "Update lodash to version 1.0.1",
    "web_url": "https://gitlab.com/foo/bar/-/merge_requests/1",
    "fixes_vulnerability": false
  }
]

Sync project

Sync project configuration with GitLab

txt

POST /api/v2/projects/{id}/sync

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path

Responses

Code Description

201

Successful response

json

{
  "id": 1,
  "name": "foo/bar",
  "forked_from_id": 2,
  "forked_from_name": null,
  "webhook_id": 3,
  "web_url": "https://gitlab.com/foo/bar",
  "configuration": {
    "updates": [
      {
        "package_manager": "docker",
        "package_ecosystem": "docker",
        "directory": "/docker",
        "registries": "*",
        "open_merge_requests_limit": 5,
        "open_security_merge_requests_limit": 10,
        "updater_options": {},
        "reject_external_code": true,
        "branch_name_prefix": "dependabot",
        "branch_name_separator": "-",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [],
        "cron": "23 16 * * * UTC",
        "rebase_strategy": {
          "strategy": "auto"
        },
        "vulnerability_alerts": {
          "enabled": true,
          "confidential": true
        }
      }
    ],
    "registries": {
      "docker-gitlab": {
        "type": "docker-registry",
        "url": "registry.gitlab.com",
        "username": "dependabot-bot"
      }
    },
    "forked": false
  }
}

Code	Description
404	Project not found

Get all update jobs

Return array of update jobs for a project

txt

GET /api/v2/projects/{id}/update_jobs

Attribute	In	Type	Required	Description
id	path	string	true	Project id or url encoded full path
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
package_ecosystem	query	string	false	Filter by package ecosystem

Responses

Code Description

200

Successful response

json

[
  {
    "id": "5d5b5c5d5e5f5a5b5c5d5e5f",
    "name": "project_name:package_ecosystem:directory",
    "package_ecosystem": "npm",
    "directory": "/",
    "enabled": true,
    "cron": "5 0 * * 6 UTC",
    "last_executed": "2025-01-10T15:15:03.474Z",
    "last_finished": "2025-01-10T15:15:03.474Z",
    "last_failures": "- Failure message",
    "project_id": 1,
    "dependency_files": [
      "package.json"
    ]
  }
]

Users

Get all users

Return array of all users

txt

GET /api/v2/users

Attribute	In	Type	Required	Description
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.

Responses

Code	Description
200	Successful response json `[ { "username": "user" } ]`

Add user

Add new user

txt

POST /api/v2/users

Attribute	In	Type	Required	Description
username	body	string	true	User name
password	body	string	true	User password

Responses

Code	Description
201	Successful response json `{ "username": "user" }`

Code	Description
409	Project already exists

Get single user

Return single user

txt

GET /api/v2/users/{username}

Attribute	In	Type	Required	Description
username	path	string	true	User name

Responses

Code	Description
200	Successful response json `{ "username": "user" }`

Code	Description
404	User not found

Update user password

txt

PUT /api/v2/users/{username}

Attribute	In	Type	Required	Description
username	path	string	true	User name
password	body	string	true	User password

Responses

Code	Description
200	Successful response json `{ "username": "user" }`

Code	Description
404	User not found

Remove user

Remove user from database

txt

DELETE /api/v2/users/{username}

Attribute	In	Type	Required	Description
username	path	string	true	User name

Responses

Code	Description
204	Removed user

Code	Description
404	User not found

Merge Requests

Get all merge requests

Return array of all merge requests

txt

GET /api/v2/merge_requests

Attribute	In	Type	Required	Description
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
state	query	string	false	Filter by state
package_ecosystem	query	string	false	Filter by package ecosystem
main_dependency	query	string	false	Filter by main dependency

Responses

Code Description

200

Successful response

json

[
  {
    "id": 1,
    "iid": 1,
    "package_ecosystem": "npm_and_yarn",
    "directory": "/",
    "state": "opened",
    "auto_merge": false,
    "squash": false,
    "update_from": "1.0.0",
    "update_to": "1.0.1",
    "main_dependency": "lodash",
    "branch": "dependabot/npm_and_yarn/lodash-1.0.1",
    "target_branch": "main",
    "target_project_id": null,
    "commit_message": "Update lodash to version 1.0.1",
    "web_url": "https://gitlab.com/foo/bar/-/merge_requests/1",
    "fixes_vulnerability": false
  }
]

Get single merge request

Return single merge request

txt

GET /api/v2/merge_requests/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Merge request id

Responses

Code Description

200

Successful response

json

{
  "id": 1,
  "iid": 1,
  "package_ecosystem": "npm_and_yarn",
  "directory": "/",
  "state": "opened",
  "auto_merge": false,
  "squash": false,
  "update_from": "1.0.0",
  "update_to": "1.0.1",
  "main_dependency": "lodash",
  "branch": "dependabot/npm_and_yarn/lodash-1.0.1",
  "target_branch": "main",
  "target_project_id": null,
  "commit_message": "Update lodash to version 1.0.1",
  "web_url": "https://gitlab.com/foo/bar/-/merge_requests/1",
  "fixes_vulnerability": false
}

Update Jobs

Get all update jobs

Return array of all update jobs

txt

GET /api/v2/update_jobs

Attribute	In	Type	Required	Description
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
package_ecosystem	query	string	false	Filter by package ecosystem

Responses

Code Description

200

Successful response

json

[
  {
    "id": "5d5b5c5d5e5f5a5b5c5d5e5f",
    "name": "project_name:package_ecosystem:directory",
    "package_ecosystem": "npm",
    "directory": "/",
    "enabled": true,
    "cron": "5 0 * * 6 UTC",
    "last_executed": "2025-01-10T15:15:03.471Z",
    "last_finished": "2025-01-10T15:15:03.471Z",
    "last_failures": "- Failure message",
    "project_id": 1,
    "dependency_files": [
      "package.json"
    ]
  }
]

Get single update job

Return single update job

txt

GET /api/v2/update_jobs/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Update job id

Responses

Code Description

200

Successful response

json

{
  "id": "5d5b5c5d5e5f5a5b5c5d5e5f",
  "name": "project_name:package_ecosystem:directory",
  "package_ecosystem": "npm",
  "directory": "/",
  "enabled": true,
  "cron": "5 0 * * 6 UTC",
  "last_executed": "2025-01-10T15:15:03.471Z",
  "last_finished": "2025-01-10T15:15:03.471Z",
  "last_failures": "- Failure message",
  "project_id": 1,
  "dependency_files": [
    "package.json"
  ]
}

Trigger update job

Trigger dependency update job

txt

POST /api/v2/update_jobs/{id}

Attribute	In	Type	Required	Description
id	path	string	true	Update job id

Responses

Code	Description
201	Successful response

Get all update job runs

Return array of all update job runs

txt

GET /api/v2/update_jobs/{id}/runs

Attribute	In	Type	Required	Description
id	path	string	true	Update job id
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
status	query	string	false	Filter by run status: success
has_failures	query	boolean	false	Filter by runs with failures

Responses

Code	Description
200	Successful response json `[ { "id": "5d5b5c5d5e5f5a5b5c5d5e5f", "created_at": "2025-01-10T15:15:03.471Z", "finished_at": "2025-01-10T15:15:03.471Z", "status": "success" } ]`

Get single update job run

Return single update job run

txt

GET /api/v2/update_jobs/{id}/runs/{run_id}

Attribute	In	Type	Required	Description
id	path	string	true	Update job id
run_id	path	string	true	Update run id

Responses

Code	Description
200	Successful response json `{ "id": "5d5b5c5d5e5f5a5b5c5d5e5f", "created_at": "2025-01-10T15:15:03.472Z", "finished_at": "2025-01-10T15:15:03.472Z", "status": "success" }`

Get update job run failures

Return array of update job run failures

txt

GET /api/v2/update_jobs/{id}/runs/{run_id}/failures

Attribute	In	Type	Required	Description
id	path	string	true	Update job id
run_id	path	string	true	Update run id
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.

Responses

Code	Description
200	Successful response json `[ { "klass": "StandardError", "message": "Error message", "backtrace": "Full error backtrace" } ]`

Get update job run log entries

Get all update job run log entries

txt

GET /api/v2/update_jobs/{id}/runs/{run_id}/log_entries

Attribute	In	Type	Required	Description
id	path	string	true	Update job id
run_id	path	string	true	Update run id
page	query	integer	false	Page offset to fetch.
per_page	query	integer	false	Number of results to return per page.
offset	query	integer	false	Pad a number of results.
log_level	query	string	false	Return log entries with given log level or above, one of `["ERROR", "INFO", "WARN", "UNKNOWN", "DEBUG", "FATAL"]`, default: `INFO`

Responses

Code	Description
200	Successful response json `[ { "timestamp": "2025-01-10T15:15:03.473Z", "log_level": "INFO", "message": "Log message" } ]`

Notify Release

Update dependency

Trigger specific dependency update for given package ecosystem across projects

txt

POST /api/v2/notify_release

Attribute	In	Type	Required	Description
dependency_name	body	string	true	Dependency name
package_ecosystem	body	string	true	Package ecosystem
project_name	body	string	false	Specific project to trigger update for
ignore_rules	body	boolean	false	Skip allow/ignore rules check when triggering update

Responses

Code	Description
201	Successfully triggered dependency update

API reference ​

Hooks ​

Process project webhook ​

Responses ​

Process system hook ​

Responses ​

Projects ​

Get all projects ​

Responses ​

Add project ​

Responses ​

Get single project ​

Responses ​

Update project ​

Responses ​

Remove project ​

Responses ​

Get all merge requests ​

Responses ​

Sync project ​

Responses ​

Get all update jobs ​

Responses ​

Users ​

Get all users ​

Responses ​

Add user ​

Responses ​

Get single user ​

Responses ​

Update user password ​

Responses ​

Remove user ​

Responses ​

Merge Requests ​

Get all merge requests ​

Responses ​

Get single merge request ​

Responses ​

Update Jobs ​

Get all update jobs ​

Responses ​

Get single update job ​

Responses ​

Trigger update job ​

Responses ​

Get all update job runs ​

Responses ​

Get single update job run ​

Responses ​

Get update job run failures ​

Responses ​

Get update job run log entries ​

Responses ​

Notify Release ​

Update dependency ​

Responses ​

API reference

Hooks

Process project webhook

Responses

Process system hook

Responses

Projects

Get all projects

Responses

Add project

Responses

Get single project

Responses

Update project

Responses

Remove project

Responses

Get all merge requests

Responses

Sync project

Responses

Get all update jobs

Responses

Users

Get all users

Responses

Add user

Responses

Get single user

Responses

Update user password

Responses

Remove user

Responses

Merge Requests

Get all merge requests

Responses

Get single merge request

Responses

Update Jobs

Get all update jobs

Responses

Get single update job

Responses

Trigger update job

Responses

Get all update job runs

Responses

Get single update job run

Responses

Get update job run failures

Responses

Get update job run log entries

Responses

Notify Release

Update dependency

Responses