Skip to content

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
AttributeInTypeRequiredDescription
X-Gitlab-TokenheaderstringfalseWebhook secret token. Required if SETTINGS__GITLAB_AUTH_TOKEN is set
postApiV2Hooksbodytrue

Responses

CodeDescription
201Successful response
CodeDescription
400Event not supported
CodeDescription
401Invalid gitlab authentication token

Process system hook

Create or update project based on received system webhook event

txt
POST /api/v2/hooks/system/project_registration
AttributeInTypeRequiredDescription
postApiV2HooksSystemProjectRegistrationbodytrue

Responses

CodeDescription
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
  }
}
CodeDescription
204Skipped, 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
AttributeInTypeRequiredDescription
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.

Responses

CodeDescription
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

Register project for dependency updates

txt
POST /api/v2/projects
AttributeInTypeRequiredDescription
postApiV2Projectsbodytrue

Responses

CodeDescription
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
  }
}
CodeDescription
409Project already exists

Get single project

Return single project

txt
GET /api/v2/projects/{id}
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
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
  }
}
CodeDescription
404Project not found

Update project

Update project attributes

txt
PUT /api/v2/projects/{id}
AttributeInTypeRequiredDescription
idpathstringtrue
putApiV2ProjectsIdbodytrue

Responses

CodeDescription
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
  }
}
CodeDescription
404Project not found

Remove project

Remove project from database

txt
DELETE /api/v2/projects/{id}
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
204Removed project
CodeDescription
404Project not found

Get all merge requests

Return array of merge requests for a project

txt
GET /api/v2/projects/{id}/merge_requests
AttributeInTypeRequiredDescription
idpathstringtrue
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
statequerystringfalseFilter by state
package_ecosystemquerystringfalseFilter by package ecosystem
main_dependencyquerystringfalseFilter by main dependency

Responses

CodeDescription
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
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
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
  }
}
CodeDescription
404Project not found

Get all update jobs

Return array of update jobs for a project

txt
GET /api/v2/projects/{id}/update_jobs
AttributeInTypeRequiredDescription
idpathstringtrue
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
package_ecosystemquerystringfalseFilter by package ecosystem

Responses

CodeDescription
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": "2024-07-13T10:47:46.591Z",
    "last_finished": "2024-07-13T10:47:46.591Z",
    "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
AttributeInTypeRequiredDescription
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.

Responses

CodeDescription
200
Successful response
json
[
  {
    "username": "user"
  }
]

Add user

Add new user

txt
POST /api/v2/users
AttributeInTypeRequiredDescription
postApiV2Usersbodytrue

Responses

CodeDescription
201
Successful response
json
{
  "username": "user"
}
CodeDescription
409Project already exists

Get single user

Return single user

txt
GET /api/v2/users/{username}
AttributeInTypeRequiredDescription
usernamepathstringtrue

Responses

CodeDescription
200
Successful response
json
{
  "username": "user"
}
CodeDescription
404User not found

Update user password

Update user password

txt
PUT /api/v2/users/{username}
AttributeInTypeRequiredDescription
usernamepathstringtrue
putApiV2UsersUsernamebodytrue

Responses

CodeDescription
200
Successful response
json
{
  "username": "user"
}
CodeDescription
404User not found

Remove user

Remove user from database

txt
DELETE /api/v2/users/{username}
AttributeInTypeRequiredDescription
usernamepathstringtrue

Responses

CodeDescription
204Removed user
CodeDescription
404User not found

Merge Requests

Get all merge requests

Return array of all merge requests

txt
GET /api/v2/merge_requests
AttributeInTypeRequiredDescription
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
statequerystringfalseFilter by state
package_ecosystemquerystringfalseFilter by package ecosystem
main_dependencyquerystringfalseFilter by main dependency

Responses

CodeDescription
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}
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
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
AttributeInTypeRequiredDescription
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
package_ecosystemquerystringfalseFilter by package ecosystem

Responses

CodeDescription
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": "2024-07-13T10:47:46.590Z",
    "last_finished": "2024-07-13T10:47:46.590Z",
    "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}
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
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": "2024-07-13T10:47:46.590Z",
  "last_finished": "2024-07-13T10:47:46.590Z",
  "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}
AttributeInTypeRequiredDescription
idpathstringtrue

Responses

CodeDescription
201Successful response

Get all update job runs

Return array of all update job runs

txt
GET /api/v2/update_jobs/{id}/runs
AttributeInTypeRequiredDescription
idpathstringtrue
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
statusquerystringfalseFilter by run status: success
has_failuresquerybooleanfalseFilter by runs with failures

Responses

CodeDescription
200
Successful response
json
[
  {
    "id": "5d5b5c5d5e5f5a5b5c5d5e5f",
    "created_at": "2024-07-13T10:47:46.590Z",
    "finished_at": "2024-07-13T10:47:46.590Z",
    "status": "success"
  }
]

Get single update job run

Return single update job run

txt
GET /api/v2/update_jobs/{id}/runs/{run_id}
AttributeInTypeRequiredDescription
idpathstringtrue
run_idpathstringtrue

Responses

CodeDescription
200
Successful response
json
{
  "id": "5d5b5c5d5e5f5a5b5c5d5e5f",
  "created_at": "2024-07-13T10:47:46.591Z",
  "finished_at": "2024-07-13T10:47:46.591Z",
  "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
AttributeInTypeRequiredDescription
idpathstringtrue
run_idpathstringtrue
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.

Responses

CodeDescription
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
AttributeInTypeRequiredDescription
idpathstringtrue
run_idpathstringtrue
pagequeryintegerfalsePage offset to fetch.
per_pagequeryintegerfalseNumber of results to return per page.
offsetqueryintegerfalsePad a number of results.
log_levelquerystringfalseReturn log entries with given log level or above, one of ["ERROR", "INFO", "WARN", "DEBUG", "FATAL", "UNKNOWN"], default: INFO

Responses

CodeDescription
200
Successful response
json
[
  {
    "timestamp": "2024-07-13T10:47:46.591Z",
    "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
AttributeInTypeRequiredDescription
postApiV2NotifyReleasebodytrue

Responses

CodeDescription
201Successfully triggered dependency update