REST API | GitLab Docs
/ REST API Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Automate your workflows and build integrations with the GitLab REST API: Create custom tools to manage your GitLab resources at scale without manual intervention. Improve collaboration by integrating GitLab data directly into your applications. Manage CI/CD processes across multiple projects with precision. Control user access programmatically to maintain consistent permissions across your organization.
The REST API uses standard HTTP methods and JSON data formats for compatibility with your existing tools and systems. Make a REST API request To make a REST API request: Submit a request to an API endpoint by using a REST API client. The GitLab instance responds to the request. It returns a status code and if applicable, the requested data. The status code indicates the outcome of the request and is useful when troubleshooting .
A REST API request must start with the root endpoint and the path. The root endpoint is the GitLab host name. The path must start with /api/v4 ( v4 represents the API version). In the following example, the API request retrieves the list of all projects on GitLab host gitlab.example.com : shell curl --request GET \ --url "https://gitlab.example.com/api/v4/projects" Access to some endpoints require authentication. For more information, see Authentication .
Rate limits REST API requests are subject to rate limit settings. These settings reduce the risk of a GitLab instance being overloaded. For details, see Rate limits . For details of the rate limit settings used by GitLab.com, see GitLab.com-specific rate limits . Response format REST API responses are returned in JSON format. Some API endpoints also support plain text format. To confirm which content type an endpoint supports, see the REST API resources .
Request requirements Some REST API requests have specific requirements, including the data format and encoding used. Request payload API requests can use parameters sent as query strings or as a payload body . GET requests usually send a query string, while PUT or POST requests usually send the payload body: Query string: shell curl --request POST \ --url "https://gitlab.example.com/api/v4/projects?name=<example-name>&description=<example-description>" Request payload (JSON): shell curl --request POST \ --header "Content-Type: application/json" \ --data '{"name":"<example-name>", "description":"<example-description>"}' \ --url "https://gitlab.example.com/api/v4/projects" URL-encoded query strings have a length limitation.
Requests that are too large result in a 414 Request-URI Too Large error message. This can be resolved by using a payload body instead. Path parameters If an endpoint has path parameters, the documentation displays them with a preceding colon. For example: DELETE /projects/:id/share/:group_id The :id path parameter needs to be replaced with the project ID, and the :group_id needs to be replaced with the ID of the group.
The colons : shouldn’t be included. The resulting cURL request for a project with ID 5 and a group ID of 17 is then: shell curl --request DELETE \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/share/17" Path parameters that are required to be URL-encoded must be followed. If not, it doesn’t match an API endpoint and responds with a 404. If there’s something in front of the API (for example, Apache), ensure that it doesn’t decode the URL-encoded path parameters. id vs iid Some API resources have two similarly-named fields.
For example, issues , merge requests , and project milestones . The fields are: id : ID that is unique across all projects. iid : Additional, internal ID (displayed in the web UI) that’s unique in the scope of a single project. If a resource has both the iid field and the id field, the iid field is usually used instead of id to fetch the resource. For example, suppose a project with id: 42 has an issue with id: 46 and iid: 5 .
In this case: A valid API request to retrieve the issue is GET /projects/42/issues/5 . An invalid API request to retrieve the issue is GET /projects/42/issues/46 . Not all resources with the iid field are fetched by iid . For guidance regarding which field to use, see the documentation for the specific resource. Encoding When making a REST API request, some content must be encoded to account for special characters and data structures.
Namespaced paths If using namespaced API requests, make sure that the NAMESPACE/PROJECT_PATH is URL-encoded. For example, / is represented by %2F : GET /api/v4/projects/diaspora%2Fdiaspora A project’s path isn’t necessarily the same as its name. A project’s path is found in the project’s URL or in the project’s settings, under General > Advanced > Change path . File path, branches, and tags name If a file path, branch, or tag contains a / , make sure it is URL-encoded.
For example, / is represented by %2F : GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master GET /api/v4/projects/1/branches/my%2Fbranch/commits GET /api/v4/projects/1/repository/tags/my%2Ftag Array and hash types You can request the API with array and hash types parameters: array import_sources is a parameter of type array : shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data "import_sources[]=github" \ --data "import_sources[]=bitbucket" \ --url "https://gitlab.example.com/api/v4/some_endpoint" hash override_params is a parameter of type hash : shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --form "namespace=email" \ --form "path=impapi" \ --form "file=@/path/to/somefile.txt" \ --form "override_params[visibility]=private" \ --form "override_params[some_other_param]=some_value" \ --url "https://gitlab.example.com/api/v4/projects/import" Array of hashes variables is a parameter of type array containing hash key/value pairs [{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }] : shell curl --globoff --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --header "Content-Type: application/json" \ --data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ --url "https://gitlab.example.com/api/v4/projects/169/pipeline" Encoding + in ISO 8601 dates If you need to include a + in a query parameter, you may need to use %2B instead, due to a W3 recommendation that causes a + to be interpreted as a space.
For example, in an ISO 8601 date, you may want to include a specific time in ISO 8601 format, such as: 2017-10-17T23:11:13.000+05:30 The correct encoding for the query parameter would be: 2017-10-17T23:11:13.000%2B05:30 Evaluating a response In some circumstances the API response may not be as you expect. Issues can include null values and redirection. If you receive a numeric status code in the response, see Status codes . null vs false In API responses, some boolean fields can have null values.
A null boolean has no default value and is neither true nor false . GitLab treats null values in boolean fields the same as false . In boolean arguments, you should only set true or false values (not null ). Redirects After path changes the REST API might respond with a message noting that the endpoint has moved. When this happens, use the endpoint specified in the Location header. Example of a project moved to a different path: shell curl --request GET \ --verbose \ --url "https://gitlab.example.com/api/v4/projects/gitlab-org%2Fold-path-project" The response is: ... < Location: http://gitlab.example.com/api/v4/projects/81 ...
This resource has been moved permanently to https://gitlab.example.com/api/v4/projects/81 The API redir
The rest of this page is on the live site.