Gitlab API

by gitlab.com

Overview

Automate GitLab interaction programmatically

Gitlab is a development API from gitlab.com. Requests are authenticated with OAuth. It is served over HTTPS. Its OpenAPI description documents 358 endpoints.

At a glance

Authentication: OAuth
HTTPS: Yes
CORS: Unknown
Category: Development
Base URL: https://gitlab.com/api
Version: v3
Endpoints: 358
OpenAPI: Specification ↗
Spec updated: 2021-06-21

Make a first request

Replace the placeholders; the documentation says exactly where credentials go.

cURL

curl -X GET "https://gitlab.com/api/v3/application/settings" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const response = await fetch("https://gitlab.com/api/v3/application/settings", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_TOKEN",
  },
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.request(
    "GET",
    "https://gitlab.com/api/v3/application/settings",
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_TOKEN",
    },
    timeout=30,
)
print(response.json())

Endpoints

Method	Path	What it does
GET	`/v3/application/settings`	Get the current application settings
PUT	`/v3/application/settings`	Modify application settings
POST	`/v3/ci/lint`	Validation of .gitlab-ci.yml content
GET	`/v3/deploy_keys`	getV3DeployKeys
GET	`/v3/dockerfiles`	Get the list of the available template
GET	`/v3/dockerfiles/{name}`	Get the text for a specific template present in local filesystem
GET	`/v3/gitignores`	Get the list of the available template
GET	`/v3/gitignores/{name}`	Get the text for a specific template present in local filesystem
GET	`/v3/gitlab_ci_ymls`	Get the list of the available template
GET	`/v3/gitlab_ci_ymls/{name}`	Get the text for a specific template present in local filesystem
GET	`/v3/groups`	Get a groups list
POST	`/v3/groups`	Create a group. Available only for users who can create groups.
GET	`/v3/groups/owned`	Get list of owned groups for authenticated user
GET	`/v3/groups/{id}`	Get a single group, with containing projects.
PUT	`/v3/groups/{id}`	Update a group. Available only for users who can administrate groups.
DELETE	`/v3/groups/{id}`	Remove a group.
GET	`/v3/groups/{id}/access_requests`	Gets a list of access requests for a group.
POST	`/v3/groups/{id}/access_requests`	Requests access for the authenticated user to a group.
DELETE	`/v3/groups/{id}/access_requests/{user_id}`	Denies an access request for the given user.
PUT	`/v3/groups/{id}/access_requests/{user_id}/approve`	Approves an access request for the given user.
GET	`/v3/groups/{id}/issues`	Get a list of group issues
GET	`/v3/groups/{id}/members`	Gets a list of group or project members viewable by the authenticated user.
POST	`/v3/groups/{id}/members`	Adds a member to a group or project.
GET	`/v3/groups/{id}/members/{user_id}`	Gets a member of a group or project.
PUT	`/v3/groups/{id}/members/{user_id}`	Updates a member of a group or project.
DELETE	`/v3/groups/{id}/members/{user_id}`	Removes a user from a group or project.
GET	`/v3/groups/{id}/notification_settings`	Get group level notification level settings, defaults to Global
PUT	`/v3/groups/{id}/notification_settings`	Update group level notification level settings, defaults to Global
GET	`/v3/groups/{id}/projects`	Get a list of projects in this group.
POST	`/v3/groups/{id}/projects/{project_id}`	Transfer a project to the group namespace. Available only for admin.
GET	`/v3/hooks`	Get the list of system hooks
POST	`/v3/hooks`	Create a new system hook
GET	`/v3/hooks/{id}`	Test a hook
DELETE	`/v3/hooks/{id}`	Delete a hook
POST	`/v3/internal/allowed`	postV3InternalAllowed
GET	`/v3/internal/broadcast_message`	getV3InternalBroadcastMessage
GET	`/v3/internal/check`	getV3InternalCheck
GET	`/v3/internal/discover`	getV3InternalDiscover
POST	`/v3/internal/lfs_authenticate`	postV3InternalLfsAuthenticate
GET	`/v3/internal/merge_request_urls`	getV3InternalMergeRequestUrls
POST	`/v3/internal/two_factor_recovery_codes`	postV3InternalTwoFactorRecoveryCodes
GET	`/v3/issues`	Get currently authenticated user's issues
GET	`/v3/keys/{id}`	Get single ssh key by id. Only available to admin users
GET	`/v3/licenses`	Get the list of the available license template
GET	`/v3/licenses/{name}`	Get the text for a specific license
GET	`/v3/namespaces`	Get a namespaces list
GET	`/v3/notification_settings`	Get global notification level settings and email, defaults to Participate
PUT	`/v3/notification_settings`	Update global notification level settings and email, defaults to Participate
GET	`/v3/projects`	Get a projects list for authenticated user
POST	`/v3/projects`	Create new project
GET	`/v3/projects/all`	Get all projects for admin user
POST	`/v3/projects/fork/{id}`	Fork new project for the current user or provided namespace.
GET	`/v3/projects/owned`	Get an owned projects list for authenticated user
GET	`/v3/projects/search/{query}`	Search for projects the current user has access to
GET	`/v3/projects/starred`	Gets starred project for the authenticated user
POST	`/v3/projects/user/{user_id}`	Create new project for a specified user. Only available to admin users.
GET	`/v3/projects/visible`	Get a list of visible projects for authenticated user
GET	`/v3/projects/{id}`	Get a single project
PUT	`/v3/projects/{id}`	Update an existing project
DELETE	`/v3/projects/{id}`	Remove a project
POST	`/v3/projects/{id}/(ref/{ref}/)trigger/builds`	Trigger a GitLab project build
GET	`/v3/projects/{id}/access_requests`	Gets a list of access requests for a project.
POST	`/v3/projects/{id}/access_requests`	Requests access for the authenticated user to a project.
DELETE	`/v3/projects/{id}/access_requests/{user_id}`	Denies an access request for the given user.
PUT	`/v3/projects/{id}/access_requests/{user_id}/approve`	Approves an access request for the given user.
POST	`/v3/projects/{id}/archive`	Archive a project
GET	`/v3/projects/{id}/boards`	Get all project boards
GET	`/v3/projects/{id}/boards/{board_id}/lists`	Get the lists of a project board
POST	`/v3/projects/{id}/boards/{board_id}/lists`	Create a new board list
GET	`/v3/projects/{id}/boards/{board_id}/lists/{list_id}`	Get a list of a project board
PUT	`/v3/projects/{id}/boards/{board_id}/lists/{list_id}`	Moves a board list to a new position
DELETE	`/v3/projects/{id}/boards/{board_id}/lists/{list_id}`	Delete a board list
GET	`/v3/projects/{id}/builds`	Get a project builds
GET	`/v3/projects/{id}/builds/artifacts/{ref_name}/download`	Download the artifacts file from build
GET	`/v3/projects/{id}/builds/{build_id}`	Get a specific build of a project
GET	`/v3/projects/{id}/builds/{build_id}/artifacts`	Download the artifacts file from build
POST	`/v3/projects/{id}/builds/{build_id}/artifacts/keep`	Keep the artifacts to prevent them from being deleted
POST	`/v3/projects/{id}/builds/{build_id}/cancel`	Cancel a specific build of a project
POST	`/v3/projects/{id}/builds/{build_id}/erase`	Erase build (remove artifacts and build trace)
POST	`/v3/projects/{id}/builds/{build_id}/play`	Trigger a manual build
POST	`/v3/projects/{id}/builds/{build_id}/retry`	Retry a specific build of a project
GET	`/v3/projects/{id}/builds/{build_id}/trace`	Get a trace of a specific build of a project
GET	`/v3/projects/{id}/deploy_keys`	Get a specific project's deploy keys
POST	`/v3/projects/{id}/deploy_keys`	Add new deploy key to currently authenticated user
GET	`/v3/projects/{id}/deploy_keys/{key_id}`	Get single deploy key
DELETE	`/v3/projects/{id}/deploy_keys/{key_id}`	Delete deploy key for a project
DELETE	`/v3/projects/{id}/deploy_keys/{key_id}/disable`	Disable a deploy key for a project
POST	`/v3/projects/{id}/deploy_keys/{key_id}/enable`	Enable a deploy key for a project
GET	`/v3/projects/{id}/deployments`	Get all deployments of the project
GET	`/v3/projects/{id}/deployments/{deployment_id}`	Gets a specific deployment
GET	`/v3/projects/{id}/environments`	Get all environments of the project
POST	`/v3/projects/{id}/environments`	Creates a new environment
PUT	`/v3/projects/{id}/environments/{environment_id}`	Updates an existing environment
DELETE	`/v3/projects/{id}/environments/{environment_id}`	Deletes an existing environment
GET	`/v3/projects/{id}/events`	Get events for a single project
DELETE	`/v3/projects/{id}/fork`	Remove a forked_from relationship
POST	`/v3/projects/{id}/fork/{forked_from_id}`	Mark this project as forked from another
GET	`/v3/projects/{id}/hooks`	Get project hooks
POST	`/v3/projects/{id}/hooks`	Add hook to project
GET	`/v3/projects/{id}/hooks/{hook_id}`	Get a project hook