summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md297
-rw-r--r--doc/api/branches.md108
-rw-r--r--doc/api/builds.md10
-rw-r--r--doc/api/commits.md265
-rw-r--r--doc/api/deploy_keys.md74
-rw-r--r--doc/api/groups.md1
-rw-r--r--doc/api/issues.md404
-rw-r--r--doc/api/labels.md152
-rw-r--r--doc/api/merge_requests.md74
-rw-r--r--doc/api/namespaces.md40
-rw-r--r--doc/api/projects.md4
-rw-r--r--doc/api/settings.md98
-rw-r--r--doc/api/system_hooks.md118
13 files changed, 1086 insertions, 559 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 2fa177ff4dd..9f3ad126320 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,7 +1,13 @@
# GitLab API
+Automate GitLab via a simple and powerful API. All definitions can be found
+under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
+
## Resources
+Documentation for various API resources can be found separately in the
+following locations:
+
- [Users](users.md)
- [Session](session.md)
- [Projects](projects.md) including setting Webhooks
@@ -27,16 +33,15 @@
- [Build triggers](build_triggers.md)
- [Build Variables](build_variables.md)
-## Clients
-
-Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients).
-You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls.
+## Authentication
-## Introduction
+All API requests require authentication. You need to pass a `private_token`
+parameter via query string or header. If passed as a header, the header name
+must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore).
+You can find or reset your private token in your account page (`/profile/account`).
-All API requests require authentication. You need to pass a `private_token` parameter by URL or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile.
-
-If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
+If `private_token` is invalid or omitted, then an error message will be
+returned with status code `401`:
```json
{
@@ -44,71 +49,83 @@ If no, or an invalid, `private_token` is provided then an error message will be
}
```
-API requests should be prefixed with `api` and the API version. The API version is defined in `lib/api.rb`.
+API requests should be prefixed with `api` and the API version. The API version
+is defined in [`lib/api.rb`][lib-api-url].
Example of a valid API request:
-```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U
+```shell
+GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK
```
-Example for a valid API request using curl and authentication via header:
+Example of a valid API request using cURL and authentication via header:
-```
-curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
```
-The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
+The API uses JSON to serialize data. You don't need to specify `.json` at the
+end of an API URL.
## Authentication with OAuth2 token
-Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter.
+Instead of the `private_token` you can transmit the OAuth2 access token as a
+header or as a parameter.
-### OAuth2 token (as a parameter)
+Example of OAuth2 token as a parameter:
-```
-curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
+```shell
+curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN
```
-### OAuth2 token (as a header)
+Example of OAuth2 token as a header:
-```
-curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
+```shell
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user
```
Read more about [GitLab as an OAuth2 client](oauth2.md).
## Status codes
-The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
-
-API request types:
-
-- `GET` requests access one or more resources and return the result as JSON
-- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
-- `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
-- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
-
-The following list shows the possible return codes for API requests.
-
-Return values:
-
-- `200 OK` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
-- `201 Created` - The `POST` request was successful and the resource is returned as JSON
-- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
-- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
-- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
-- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
-- `405 Method Not Allowed` - The request is not supported
-- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
-- `422 Unprocessable` - The entity could not be processed
-- `500 Server Error` - While handling the request something went wrong on the server side
+The API is designed to return different status codes according to context and
+action. This way, if a request results in an error, the caller is able to get
+insight into what went wrong.
+
+The following table gives an overview of how the API functions generally behave.
+
+| Request type | Description |
+| ------------ | ----------- |
+| `GET` | Access one or more resources and return the result as JSON. |
+| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
+| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
+| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
+
+The following table shows the possible return codes for API requests.
+
+| Return values | Description |
+| ------------- | ----------- |
+| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
+| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
+| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
+| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
+| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
+| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
+| `405 Method Not Allowed` | The request is not supported. |
+| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
+| `422 Unprocessable` | The entity could not be processed. |
+| `500 Server Error` | While handling the request something went wrong server-side. |
## Sudo
-All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass `sudo` parameter by URL or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals).
+All API requests support performing an API call as if you were another user,
+provided your private token is from an administrator account. You need to pass
+the `sudo` parameter either via query string or a header with an ID/username of
+the user you want to perform the operation as. If passed as a header, the
+header name must be `SUDO` (uppercase).
-If a non administrative `private_token` is provided then an error message will be returned with status code 403:
+If a non administrative `private_token` is provided, then an error message will
+be returned with status code `403`:
```json
{
@@ -116,7 +133,8 @@ If a non administrative `private_token` is provided then an error message will b
}
```
-If the sudo user id or username cannot be found then an error message will be returned with status code 404:
+If the sudo user ID or username cannot be found, an error message will be
+returned with status code `404`:
```json
{
@@ -124,94 +142,181 @@ If the sudo user id or username cannot be found then an error message will be re
}
```
-Example of a valid API with sudo request:
+---
+
+Example of a valid API call and a request using cURL with sudo request,
+providing a username:
+```shell
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username
+
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects"
```
+Example of a valid API call and a request using cURL with sudo request,
+providing an ID:
+
+```shell
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
```
-GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23
+
+```shell
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects"
```
-Example for a valid API request with sudo using curl and authentication via header:
+## Pagination
+
+Sometimes the returned result will span across many pages. When listing
+resources you can pass the following parameters:
+| Parameter | Description |
+| --------- | ----------- |
+| `page` | Page number (default: `1`) |
+| `per_page`| Number of items to list per page (default: `20`, max: `100`) |
+
+In the example below, we list 50 [namespaces](namespaces.md) per page.
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50
```
-curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "http://example.com/api/v3/projects"
+
+### Pagination Link header
+
+[Link headers](http://www.w3.org/wiki/LinkHeader) are sent back with each
+response. They have `rel` set to prev/next/first/last and contain the relevant
+URL. Please use these links instead of generating your own URLs.
+
+In the cURL example below, we limit the output to 3 items per page (`per_page=3`)
+and we request the second page (`page=2`) of [comments](notes.md) of the issue
+with ID `8` which belongs to the project with ID `8`:
+
+```bash
+curl -I -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/8/issues/8/notes?per_page=3&page=2
```
+The response will then be:
+
```
-curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
+HTTP/1.1 200 OK
+Cache-Control: no-cache
+Content-Length: 1103
+Content-Type: application/json
+Date: Mon, 18 Jan 2016 09:43:18 GMT
+Link: <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
+Status: 200 OK
+Vary: Origin
+X-Next-Page: 3
+X-Page: 2
+X-Per-Page: 3
+X-Prev-Page: 1
+X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86
+X-Runtime: 0.108688
+X-Total: 8
+X-Total-Pages: 3
```
-## Pagination
+### Other pagination headers
-When listing resources you can pass the following parameters:
+Additional pagination headers are also sent back.
-- `page` (default: `1`) - page number
-- `per_page` (default: `20`, max: `100`) - number of items to list per page
+| Header | Description |
+| ------ | ----------- |
+| `X-Total` | The total number of items |
+| `X-Total-Pages` | The total number of pages |
+| `X-Per-Page` | The number of items per page |
+| `X-Page` | The index of the current page (starting at 1) |
+| `X-Next-Page` | The index of the next page |
+| `X-Prev-Page` | The index of the previous page |
-[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own URLs.
+## `id` vs `iid`
-## id vs iid
+When you work with the API, you may notice two similar fields in API entities:
+`id` and `iid`. The main difference between them is scope.
-When you work with API you may notice two similar fields in api entities: id and iid. The main difference between them is scope. Example:
+For example, an issue might have `id: 46` and `iid: 5`.
-Issue:
+| Parameter | Description |
+| --------- | ----------- |
+| `id` | Is unique across all issues and is used for any API call |
+| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` |
- id: 46
- iid: 5
+That means that if you want to get an issue via the API you should use the `id`:
-- id - is unique across all issues. It's used for any api call.
-- iid - is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see iid.
+```bash
+GET /projects/42/issues/:id
+```
-So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use `http:://host/project/issues/:iid.json`
+On the other hand, if you want to create a link to a web page you should use
+the `iid`:
+
+```bash
+GET /projects/42/issues/:iid
+```
## Data validation and error reporting
-When working with the API you may encounter validation errors. In such case, the API will answer with an HTTP `400` status.
+When working with the API you may encounter validation errors, in which case
+the API will answer with an HTTP `400` status.
+
Such errors appear in two cases:
-* A required attribute of the API request is missing, e.g. the title of an issue is not given
-* An attribute did not pass the validation, e.g. user bio is too long
+- A required attribute of the API request is missing, e.g., the title of an
+ issue is not given
+- An attribute did not pass the validation, e.g., user bio is too long
When an attribute is missing, you will get something like:
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
-
- {
- "message":"400 (Bad request) \"title\" not given"
- }
-
-When a validation error occurs, error messages will be different. They will hold all details of validation errors:
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message":"400 (Bad request) \"title\" not given"
+}
+```
- HTTP/1.1 400 Bad Request
- Content-Type: application/json
+When a validation error occurs, error messages will be different. They will
+hold all details of validation errors:
- {
- "message": {
- "bio": [
- "is too long (maximum is 255 characters)"
- ]
- }
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message": {
+ "bio": [
+ "is too long (maximum is 255 characters)"
+ ]
}
+}
+```
-This makes error messages more machine-readable. The format can be described as follow:
+This makes error messages more machine-readable. The format can be described as
+follows:
- {
- "message": {
+```json
+{
+ "message": {
+ "<property-name>": [
+ "<error-message>",
+ "<error-message>",
+ ...
+ ],
+ "<embed-entity>": {
"<property-name>": [
"<error-message>",
"<error-message>",
...
],
- "<embed-entity>": {
- "<property-name>": [
- "<error-message>",
- "<error-message>",
- ...
- ],
- }
}
}
+}
+```
+
+## Clients
+
+There are many unofficial GitLab API Clients for most of the popular
+programming languages. Visit the [GitLab website] for a complete list.
+
+[GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API"
+[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 6a9c10c8520..abc4732c395 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically.
GET /projects/:id/repository/branches
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
-- `id` (required) - The ID of a project
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches
+```
+
+Example response:
```json
[
{
+ "name": "master",
+ "protected": true,
"commit": {
"author_email": "john@example.com",
"author_name": "John Smith",
@@ -27,10 +35,9 @@ Parameters:
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
- },
- "name": "master",
- "protected": true
- }
+ }
+ },
+ ...
]
```
@@ -42,13 +49,21 @@ Get a single project repository branch.
GET /projects/:id/repository/branches/:branch
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master
+```
+
+Example response:
```json
{
+ "name": "master",
+ "protected": true,
"commit": {
"author_email": "john@example.com",
"author_name": "John Smith",
@@ -61,25 +76,30 @@ Parameters:
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
- },
- "name": "master",
- "protected": true
+ }
}
```
## Protect repository branch
-Protects a single project repository branch. This is an idempotent function, protecting an already
-protected repository branch still returns a `200 OK` status code.
+Protects a single project repository branch. This is an idempotent function,
+protecting an already protected repository branch still returns a `200 OK`
+status code.
```
PUT /projects/:id/repository/branches/:branch/protect
```
-Parameters:
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/protect
+```
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
+
+Example response:
```json
{
@@ -103,17 +123,24 @@ Parameters:
## Unprotect repository branch
-Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
-unprotected repository branch still returns a `200 OK` status code.
+Unprotects a single project repository branch. This is an idempotent function,
+unprotecting an already unprotected repository branch still returns a `200 OK`
+status code.
```
PUT /projects/:id/repository/branches/:branch/unprotect
```
-Parameters:
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+Example response:
```json
{
@@ -141,11 +168,17 @@ Parameters:
POST /projects/:id/repository/branches
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch_name` | string | yes | The name of the branch |
+| `ref` | string | yes | The branch name or commit SHA to create branch from |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master"
+```
-- `id` (required) - The ID of a project
-- `branch_name` (required) - The name of the branch
-- `ref` (required) - Create branch from commit SHA or existing branch
+Example response:
```json
{
@@ -162,12 +195,13 @@ Parameters:
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]
},
- "name": "master",
+ "name": "newbranch",
"protected": false
}
```
-It return 200 if succeed or 400 if failed with error message explaining reason.
+It returns `200` if it succeeds or `400` if failed with an error message
+explaining the reason.
## Delete repository branch
@@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason.
DELETE /projects/:id/repository/branches/:branch
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `branch` | string | yes | The name of the branch |
-- `id` (required) - The ID of a project
-- `branch` (required) - The name of the branch
+It returns `200` if it succeeds, `404` if the branch to be deleted does not exist
+or `400` for other reasons. In case of an error, an explaining message is provided.
-It return 200 if succeed, 404 if the branch to be deleted does not exist
-or 400 for other reasons. In case of an error, an explaining message is provided.
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch"
+```
-Success response:
+Example response:
```json
{
- "branch_name": "my-removed-branch"
+ "branch_name": "newbranch"
}
```
diff --git a/doc/api/builds.md b/doc/api/builds.md
index ecb50754c88..6e64d096644 100644
--- a/doc/api/builds.md
+++ b/doc/api/builds.md
@@ -18,7 +18,7 @@ GET /projects/:id/builds
### Example of request
```
-curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
```
### Example of response
@@ -123,7 +123,7 @@ GET /projects/:id/repository/commits/:sha/builds
### Example of request
```
-curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
```
### Example of response
@@ -213,7 +213,7 @@ GET /projects/:id/builds/:build_id
### Example of request
```
-curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
```
### Example of response
@@ -277,7 +277,7 @@ POST /projects/:id/builds/:build_id/cancel
### Example of request
```
-curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
```
### Example of response
@@ -327,7 +327,7 @@ POST /projects/:id/builds/:build_id/retry
### Example of request
```
-curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
```
### Example of response
diff --git a/doc/api/commits.md b/doc/api/commits.md
index 93d62b751e6..e4d436b8e52 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -8,10 +8,16 @@ Get a list of repository commits in a project.
GET /projects/:id/repository/commits
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits"
+```
-- `id` (required) - The ID of a project
-- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
+Example response:
```json
[
@@ -48,8 +54,16 @@ GET /projects/:id/repository/commits/:sha
Parameters:
-- `id` (required) - The ID of a project
-- `sha` (required) - The commit hash or name of a repository branch or tag
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master
+```
+
+Example response:
```json
{
@@ -79,8 +93,16 @@ GET /projects/:id/repository/commits/:sha/diff
Parameters:
-- `id` (required) - The ID of a project
-- `sha` (required) - The name of a repository branch or tag or if not given the default branch
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/diff"
+```
+
+Example response:
```json
[
@@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments
Parameters:
-- `id` (required) - The ID of a project
-- `sha` (required) - The name of a repository branch or tag or if not given the default branch
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit hash or name of a repository branch or tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments"
+```
+
+Example response:
```json
[
@@ -128,39 +158,65 @@ Parameters:
## Post comment to commit
-Adds a comment to a commit. Optionally you can post comments on a specific line of a commit. Therefor both `path`, `line_new` and `line_old` are required.
+Adds a comment to a commit.
+
+In order to post a comment in a particular line of a particular file, you must
+specify the full commit SHA, the `path`, the `line` and `line_type` should be
+`new`.
+
+The comment will be added at the end of the last commit if at least one of the
+cases below is valid:
+
+- the `sha` is instead a branch or a tag and the `line` or `path` are invalid
+- the `line` number is invalid (does not exist)
+- the `path` is invalid (does not exist)
+
+In any of the above cases, the response of `line`, `line_type` and `path` is
+set to `null`.
```
POST /projects/:id/repository/commits/:sha/comments
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `sha` | string | yes | The commit SHA or name of a repository branch or tag |
+| `note` | string | yes | The text of the comment |
+| `path` | string | no | The file path relative to the repository |
+| `line` | integer | no | The line number where the comment should be placed |
+| `line_type` | string | no | The line type. Takes `new` or `old` as arguments |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "note=Nice picture man\!" -F "path=dudeism.md" -F "line=11" -F "line_type=new" https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments
+```
-- `id` (required) - The ID of a project
-- `sha` (required) - The name of a repository branch or tag or if not given the default branch
-- `note` (required) - Text of comment
-- `path` (optional) - The file path
-- `line` (optional) - The line number
-- `line_type` (optional) - The line type (new or old)
+Example response:
```json
{
- "author": {
- "id": 1,
- "username": "admin",
- "email": "admin@local.host",
- "name": "Administrator",
- "blocked": false,
- "created_at": "2012-04-29T08:46:00Z"
- },
- "note": "text1",
- "path": "example.rb",
- "line": 5,
- "line_type": "new"
+ "author" : {
+ "web_url" : "https://gitlab.example.com/u/thedude",
+ "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+ "username" : "thedude",
+ "state" : "active",
+ "name" : "Jeff Lebowski",
+ "id" : 28
+ },
+ "created_at" : "2016-01-19T09:44:55.600Z",
+ "line_type" : "new",
+ "path" : "dudeism.md",
+ "line" : 11,
+ "note" : "Nice picture man!"
}
```
-## Get the status of a commit
+## Commit status
+
+Since GitLab 8.1, this is the new commit status API. The documentation in
+[ci/api/commits](../ci/api/commits.md) is deprecated.
+
+### Get the status of a commit
Get the statuses of a commit in a project.
@@ -168,75 +224,116 @@ Get the statuses of a commit in a project.
GET /projects/:id/repository/commits/:sha/statuses
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project
+| `sha` | string | yes | The commit SHA
+| `ref_name`| string | no | The name of a repository branch or tag or, if not given, the default branch
+| `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test`
+| `name` | string | no | Filter by [job name](../ci/yaml/README.md#jobs), e.g., `bundler:audit`
+| `all` | boolean | no | Return all statuses, not only the latest ones
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses
+```
-- `id` (required) - The ID of a project
-- `sha` (required) - The commit SHA
-- `ref` (optional) - Filter by ref name, it can be branch or tag
-- `stage` (optional) - Filter by stage
-- `name` (optional) - Filer by status name, eg. jenkins
-- `all` (optional) - The flag to return all statuses, not only latest ones
+Example response:
```json
[
- {
- "id": 13,
- "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
- "ref": "test",
- "status": "success",
- "name": "ci/jenkins",
- "target_url": "http://jenkins/project/url",
- "description": "Jenkins success",
- "created_at": "2015-10-12T09:47:16.250Z",
- "started_at": "2015-10-12T09:47:16.250Z",
- "finished_at": "2015-10-12T09:47:16.262Z",
- "author": {
- "id": 1,
- "username": "admin",
- "email": "admin@local.host",
- "name": "Administrator",
- "blocked": false,
- "created_at": "2012-04-29T08:46:00Z"
- }
- }
+ ...
+
+ {
+ "status" : "pending",
+ "created_at" : "2016-01-19T08:40:25.934Z",
+ "started_at" : null,
+ "name" : "bundler:audit",
+ "allow_failure" : true,
+ "author" : {
+ "username" : "thedude",
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/thedude",
+ "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+ "id" : 28,
+ "name" : "Jeff Lebowski"
+ },
+ "description" : null,
+ "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+ "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/91",
+ "finished_at" : null,
+ "id" : 91,
+ "ref" : "master"
+ },
+ {
+ "started_at" : null,
+ "name" : "flay",
+ "allow_failure" : false,
+ "status" : "pending",
+ "created_at" : "2016-01-19T08:40:25.832Z",
+ "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/90",
+ "id" : 90,
+ "finished_at" : null,
+ "ref" : "master",
+ "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+ "author" : {
+ "id" : 28,
+ "name" : "Jeff Lebowski",
+ "username" : "thedude",
+ "web_url" : "https://gitlab.example.com/u/thedude",
+ "state" : "active",
+ "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"
+ },
+ "description" : null
+ },
+
+ ...
]
```
-## Post the status to commit
+### Post the build status to a commit
-Adds or updates a status of a commit.
+Adds or updates a build status of a commit.
```
POST /projects/:id/statuses/:sha
```
-- `id` (required) - The ID of a project
-- `sha` (required) - The commit SHA
-- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled
-- `ref` (optional) - The ref (branch or tag) to which the status refers
-- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default"
-- `target_url` (optional) - The target URL to associate with this status
-- `description` (optional) - The short description of the status
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project
+| `sha` | string | yes | The commit SHA
+| `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled`
+| `ref` | string | no | The `ref` (branch or tag) to which the status refers
+| `name` or `context` | string | no | The label to differentiate this status from the status of other systems. Default value is `default`
+| `target_url` | string | no | The target URL to associate with this status
+| `description` | string | no | The short description of the status
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
+```
+
+Example response:
```json
{
- "id": 13,
- "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
- "ref": "test",
- "status": "success",
- "name": "ci/jenkins",
- "target_url": "http://jenkins/project/url",
- "description": "Jenkins success",
- "created_at": "2015-10-12T09:47:16.250Z",
- "started_at": "2015-10-12T09:47:16.250Z",
- "finished_at": "2015-10-12T09:47:16.262Z",
- "author": {
- "id": 1,
- "username": "admin",
- "email": "admin@local.host",
- "name": "Administrator",
- "blocked": false,
- "created_at": "2012-04-29T08:46:00Z"
- }
+ "author" : {
+ "web_url" : "https://gitlab.example.com/u/thedude",
+ "name" : "Jeff Lebowski",
+ "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
+ "username" : "thedude",
+ "state" : "active",
+ "id" : 28
+ },
+ "name" : "default",
+ "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
+ "status" : "success",
+ "description" : null,
+ "id" : 93,
+ "target_url" : null,
+ "ref" : null,
+ "started_at" : null,
+ "created_at" : "2016-01-19T09:05:50.355Z",
+ "allow_failure" : false,
+ "finished_at" : "2016-01-19T09:05:50.365Z"
}
```
diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index e4492fc609c..9da1fe22e61 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -8,9 +8,15 @@ Get a list of a project's deploy keys.
GET /projects/:id/keys
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys"
+```
-- `id` (required) - The ID of the project
+Example response:
```json
[
@@ -39,8 +45,16 @@ GET /projects/:id/keys/:key_id
Parameters:
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `key_id` | integer | yes | The ID of the deploy key |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/11"
+```
+
+Example response:
```json
{
@@ -54,17 +68,34 @@ Parameters:
## Add deploy key
Creates a new deploy key for a project.
-If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user
+
+If the deploy key already exists in another project, it will be joined to current
+project only if original one was is accessible by the same user.
```
POST /projects/:id/keys
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `title` | string | yes | New deploy key's title |
+| `key` | string | yes | New deploy key |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v3/projects/5/keys/"
+```
-- `id` (required) - The ID of the project
-- `title` (required) - New deploy key's title
-- `key` (required) - New deploy key
+Example response:
+
+```json
+{
+ "key" : "ssh-rsa AAAA...",
+ "id" : 12,
+ "title" : "My deploy key",
+ "created_at" : "2015-08-29T12:44:31.550Z"
+}
+```
## Delete deploy key
@@ -74,7 +105,26 @@ Delete a deploy key from a project
DELETE /projects/:id/keys/:key_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `key_id` | integer | yes | The ID of the deploy key |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/13"
+```
-- `id` (required) - The ID of the project
-- `key_id` (required) - The ID of the deploy key
+Example response:
+
+```json
+{
+ "updated_at" : "2015-08-29T12:50:57.259Z",
+ "key" : "ssh-rsa AAAA...",
+ "public" : false,
+ "title" : "My deploy key",
+ "user_id" : null,
+ "created_at" : "2015-08-29T12:50:57.259Z",
+ "fingerprint" : "6a:33:1f:74:51:c0:39:81:79:ec:7a:31:f8:40:20:43",
+ "id" : 13
+}
+```
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 808675d8605..d47e79ba47f 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -33,6 +33,7 @@ GET /groups/:id/projects
Parameters:
- `archived` (optional) - if passed, limit by archived status
+- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private`
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
diff --git a/doc/api/issues.md b/doc/api/issues.md
index d407bc35d79..9e704648b25 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,9 +1,20 @@
# Issues
+Every API call to issues must be authenticated.
+
+If a user is not a member of a project and the project is private, a `GET`
+request on that project will result to a `404` status code.
+
+## Issues pagination
+
+By default, `GET` requests return 20 results at a time because the API results
+are paginated.
+
+Read more on [pagination](README.md#pagination).
+
## List issues
-Get all issues created by authenticated user. This function takes pagination parameters
-`page` and `per_page` to restrict the list of issues.
+Get all issues created by the authenticated user.
```
GET /issues
@@ -14,81 +25,65 @@ GET /issues?labels=foo,bar
GET /issues?labels=foo,bar&state=opened
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
+| `labels` | string | no | Comma-separated list of label names |
+| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
+| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/issues
+```
-- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
-- `labels` (optional) - Comma-separated list of label names
-- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+Example response:
```json
[
- {
- "id": 43,
- "iid": 3,
- "project_id": 8,
- "title": "4xx/5xx pages",
- "description": "",
- "labels": [],
- "milestone": null,
- "assignee": null,
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "closed",
- "updated_at": "2012-07-02T17:53:12Z",
- "created_at": "2012-07-02T17:53:12Z"
- },
- {
- "id": 42,
- "iid": 4,
- "project_id": 8,
- "title": "Add user settings",
- "description": "",
- "labels": [
- "feature"
- ],
- "milestone": {
- "id": 1,
- "title": "v1.0",
- "description": "",
- "due_date": "2012-07-20",
- "state": "reopened",
- "updated_at": "2012-07-04T13:42:48Z",
- "created_at": "2012-07-04T13:42:48Z"
- },
- "assignee": {
- "id": 2,
- "username": "jack_smith",
- "email": "jack@example.com",
- "name": "Jack Smith",
- "state": "active",
- "created_at": "2012-05-23T08:01:01Z"
- },
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "opened",
- "updated_at": "2012-07-12T13:43:19Z",
- "created_at": "2012-06-28T12:58:06Z"
- }
+ {
+ "state" : "opened",
+ "description" : "Ratione dolores corrupti mollitia soluta quia.",
+ "author" : {
+ "state" : "active",
+ "id" : 18,
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe",
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "username" : "eileen.lowe"
+ },
+ "milestone" : {
+ "project_id" : 1,
+ "description" : "Ducimus nam enim ex consequatur cumque ratione.",
+ "state" : "closed",
+ "due_date" : null,
+ "iid" : 2,
+ "created_at" : "2016-01-04T15:31:39.996Z",
+ "title" : "v4.0",
+ "id" : 17,
+ "updated_at" : "2016-01-04T15:31:39.996Z"
+ },
+ "project_id" : 1,
+ "assignee" : {
+ "state" : "active",
+ "id" : 1,
+ "name" : "Administrator",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root"
+ },
+ "updated_at" : "2016-01-04T15:31:51.081Z",
+ "id" : 76,
+ "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
+ "created_at" : "2016-01-04T15:31:51.081Z",
+ "iid" : 6,
+ "labels" : []
+ },
]
```
## List project issues
-Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
-to return the list of project issues.
+Get a list of a project's issues.
```
GET /projects/:id/issues
@@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened
GET /projects/:id/issues?iid=42
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `iid` | integer | no | Return the issue having the given `iid` |
+| `state` | string | no | Return all issues or just those that are `opened` or `closed`|
+| `labels` | string | no | Comma-separated list of label names |
+| `milestone` | string| no | The milestone title |
+| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
+| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
+
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues
+```
+
+Example response:
-- `id` (required) - The ID of a project
-- `iid` (optional) - Return the issue having the given `iid`
-- `state` (optional) - Return `all` issues or just those that are `opened` or `closed`
-- `labels` (optional) - Comma-separated list of label names
-- `milestone` (optional) - Milestone title
-- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`
-- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
+```json
+[
+ {
+ "project_id" : 4,
+ "milestone" : {
+ "due_date" : null,
+ "project_id" : 4,
+ "state" : "closed",
+ "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+ "iid" : 3,
+ "id" : 11,
+ "title" : "v3.0",
+ "created_at" : "2016-01-04T15:31:39.788Z",
+ "updated_at" : "2016-01-04T15:31:39.788Z"
+ },
+ "author" : {
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root",
+ "id" : 1,
+ "name" : "Administrator"
+ },
+ "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+ "state" : "closed",
+ "iid" : 1,
+ "assignee" : {
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/u/lennie",
+ "state" : "active",
+ "username" : "lennie",
+ "id" : 9,
+ "name" : "Dr. Luella Kovacek"
+ },
+ "labels" : [],
+ "id" : 41,
+ "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+ "updated_at" : "2016-01-04T15:31:46.176Z",
+ "created_at" : "2016-01-04T15:31:46.176Z"
+ }
+]
+```
## Single issue
-Gets a single project issue.
+Get a single project issue.
```
GET /projects/:id/issues/:issue_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `issue_id`| integer | yes | The ID of a project's issue |
-- `id` (required) - The ID of a project
-- `issue_id` (required) - The ID of a project issue
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41
+```
+
+Example response:
```json
{
- "id": 42,
- "iid": 3,
- "project_id": 8,
- "title": "Add user settings",
- "description": "",
- "labels": [
- "feature"
- ],
- "milestone": {
- "id": 1,
- "title": "v1.0",
- "description": "",
- "due_date": "2012-07-20",
- "state": "closed",
- "updated_at": "2012-07-04T13:42:48Z",
- "created_at": "2012-07-04T13:42:48Z"
- },
- "assignee": {
- "id": 2,
- "username": "jack_smith",
- "email": "jack@example.com",
- "name": "Jack Smith",
- "state": "active",
- "created_at": "2012-05-23T08:01:01Z"
- },
- "author": {
- "id": 1,
- "username": "john_smith",
- "email": "john@example.com",
- "name": "John Smith",
- "state": "active",
- "created_at": "2012-05-23T08:00:58Z"
- },
- "state": "opened",
- "updated_at": "2012-07-12T13:43:19Z",
- "created_at": "2012-06-28T12:58:06Z"
+ "project_id" : 4,
+ "milestone" : {
+ "due_date" : null,
+ "project_id" : 4,
+ "state" : "closed",
+ "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.",
+ "iid" : 3,
+ "id" : 11,
+ "title" : "v3.0",
+ "created_at" : "2016-01-04T15:31:39.788Z",
+ "updated_at" : "2016-01-04T15:31:39.788Z"
+ },
+ "author" : {
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/root",
+ "avatar_url" : null,
+ "username" : "root",
+ "id" : 1,
+ "name" : "Administrator"
+ },
+ "description" : "Omnis vero earum sunt corporis dolor et placeat.",
+ "state" : "closed",
+ "iid" : 1,
+ "assignee" : {
+ "avatar_url" : null,
+ "web_url" : "https://gitlab.example.com/u/lennie",
+ "state" : "active",
+ "username" : "lennie",
+ "id" : 9,
+ "name" : "Dr. Luella Kovacek"
+ },
+ "labels" : [],
+ "id" : 41,
+ "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.",
+ "updated_at" : "2016-01-04T15:31:46.176Z",
+ "created_at" : "2016-01-04T15:31:46.176Z"
}
```
@@ -170,57 +221,122 @@ Parameters:
Creates a new project issue.
+If the operation is successful, a status code of `200` and the newly-created
+issue is returned. If an error occurs, an error number and a message explaining
+the reason is returned.
+
```
POST /projects/:id/issues
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `title` | string | yes | The title of an issue |
+| `description` | string | no | The description of an issue |
+| `assignee_id` | integer | no | The ID of a user to assign issue |
+| `milestone_id` | integer | no | The ID of a milestone to assign issue |
+| `labels` | string | no | Comma-separated label names for an issue |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug
+```
-- `id` (required) - The ID of a project
-- `title` (required) - The title of an issue
-- `description` (optional) - The description of an issue
-- `assignee_id` (optional) - The ID of a user to assign issue
-- `milestone_id` (optional) - The ID of a milestone to assign issue
-- `labels` (optional) - Comma-separated label names for an issue
+Example response:
-If the operation is successful, 200 and the newly created issue is returned.
-If an error occurs, an error number and a message explaining the reason is returned.
+```json
+{
+ "project_id" : 4,
+ "id" : 84,
+ "created_at" : "2016-01-07T12:44:33.959Z",
+ "iid" : 14,
+ "title" : "Issues with auth",
+ "state" : "opened",
+ "assignee" : null,
+ "labels" : [
+ "bug"
+ ],
+ "author" : {
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe",
+ "id" : 18,
+ "username" : "eileen.lowe"
+ },
+ "description" : null,
+ "updated_at" : "2016-01-07T12:44:33.959Z",
+ "milestone" : null
+}
+```
## Edit issue
-Updates an existing project issue. This function is also used to mark an issue as closed.
+Updates an existing project issue. This call is also used to mark an issue as
+closed.
+
+If the operation is successful, a code of `200` and the updated issue is
+returned. If an error occurs, an error number and a message explaining the
+reason is returned.
```
PUT /projects/:id/issues/:issue_id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+| `title` | string | no | The title of an issue |
+| `description` | string | no | The description of an issue |
+| `assignee_id` | integer | no | The ID of a user to assign the issue to |
+| `milestone_id` | integer | no | The ID of a milestone to assign the issue to |
+| `labels` | string | no | Comma-separated label names for an issue |
+| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it |
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/85?state_event=close
+```
-- `id` (required) - The ID of a project
-- `issue_id` (required) - The ID of a project's issue
-- `title` (optional) - The title of an issue
-- `description` (optional) - The description of an issue
-- `assignee_id` (optional) - The ID of a user to assign issue
-- `milestone_id` (optional) - The ID of a milestone to assign issue
-- `labels` (optional) - Comma-separated label names for an issue
-- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it)
+Example response:
-If the operation is successful, 200 and the updated issue is returned.
-If an error occurs, an error number and a message explaining the reason is returned.
+```json
+{
+ "created_at" : "2016-01-07T12:46:01.410Z",
+ "author" : {
+ "name" : "Alexandra Bashirian",
+ "avatar_url" : null,
+ "username" : "eileen.lowe",
+ "id" : 18,
+ "state" : "active",
+ "web_url" : "https://gitlab.example.com/u/eileen.lowe"
+ },
+ "state" : "closed",
+ "title" : "Issues with auth",
+ "project_id" : 4,
+ "description" : null,
+ "updated_at" : "2016-01-07T12:55:16.213Z",
+ "iid" : 15,
+ "labels" : [
+ "bug"
+ ],
+ "id" : 85,
+ "assignee" : null,
+ "milestone" : null
+}
+```
## Delete existing issue (**Deprecated**)
-The function is deprecated and returns a `405 Method Not Allowed` error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with parameter `state_event` set to `close`.
+This call is deprecated and returns a `405 Method Not Allowed` error if called.
+An issue gets now closed and is done by calling
+`PUT /projects/:id/issues/:issue_id` with the parameter `state_event` set to
+`close`. See [edit issue](#edit-issue) for more details.
```
DELETE /projects/:id/issues/:issue_id
```
-Parameters:
-
-- `id` (required) - The project ID
-- `issue_id` (required) - The ID of the issue
-
## Comments on issues
-Comments are done via the notes resource.
+Comments are done via the [notes](notes.md) resource.
diff --git a/doc/api/labels.md b/doc/api/labels.md
index de41f35d284..6496ffe9fd1 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -2,83 +2,153 @@
## List labels
-Get all labels for given project.
+Get all labels for a given project.
```
GET /projects/:id/labels
```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels
+```
+
+Example response:
+
```json
[
- {
- "name": "Awesome",
- "color": "#DD10AA"
- },
- {
- "name": "Documentation",
- "color": "#1E80DD"
- },
- {
- "name": "Feature",
- "color": "#11FF22"
- },
- {
- "name": "Bug",
- "color": "#EE1122"
- }
+ {
+ "name" : "bug",
+ "color" : "#d9534f"
+ },
+ {
+ "color" : "#d9534f",
+ "name" : "confirmed"
+ },
+ {
+ "name" : "critical",
+ "color" : "#d9534f"
+ },
+ {
+ "color" : "#428bca",
+ "name" : "discussion"
+ },
+ {
+ "name" : "documentation",
+ "color" : "#f0ad4e"
+ },
+ {
+ "color" : "#5cb85c",
+ "name" : "enhancement"
+ },
+ {
+ "color" : "#428bca",
+ "name" : "suggestion"
+ },
+ {
+ "color" : "#f0ad4e",
+ "name" : "support"
+ }
]
```
## Create a new label
-Creates a new label for given repository with given name and color.
+Creates a new label for the given repository with the given name and color.
+
+It returns 200 if the label was successfully created, 400 for wrong parameters
+and 409 if the label already exists.
```
POST /projects/:id/labels
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the label |
+| `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the label
-- `color` (required) - Color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+Example response:
-It returns 200 and the newly created label, if the operation succeeds.
-If the label already exists, 409 and an error message is returned.
-If label parameters are invalid, 400 and an explaining error message is returned.
+```json
+{
+ "name" : "feature",
+ "color" : "#5843AD"
+}
+```
## Delete a label
-Deletes a label given by its name.
+Deletes a label with a given name.
+
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
```
DELETE /projects/:id/labels
```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the label to be deleted
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the label |
-It returns 200 if the label successfully was deleted, 400 for wrong parameters
-and 404 if the label does not exist.
-In case of an error, additionally an error message is returned.
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug"
+```
+
+Example response:
+
+```json
+{
+ "title" : "feature",
+ "color" : "#5843AD",
+ "updated_at" : "2015-11-03T21:22:30.737Z",
+ "template" : false,
+ "project_id" : 1,
+ "created_at" : "2015-11-03T21:22:30.737Z",
+ "id" : 9
+}
+```
## Edit an existing label
-Updates an existing label with new name or now color. At least one parameter
+Updates an existing label with new name or new color. At least one parameter
is required, to update the label.
+It returns 200 if the label was successfully deleted, 400 for wrong parameters
+and 404 if the label does not exist.
+In case of an error, an additional error message is returned.
+
```
PUT /projects/:id/labels
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the project |
+| `name` | string | yes | The name of the existing label |
+| `new_name` | string | yes if `color` if not provided | The new name of the label |
+| `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
+
+```bash
+curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
+```
-- `id` (required) - The ID of a project
-- `name` (required) - The name of the existing label
-- `new_name` (optional) - The new name of the label
-- `color` (optional) - New color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)
+Example response:
-On success, this method returns 200 with the updated label.
-If required parameters are missing or parameters are invalid, 400 is returned.
-If the label to be updated is missing, 404 is returned.
-In case of an error, additionally an error message is returned.
+```json
+{
+ "color" : "#8E44AD",
+ "name" : "docs"
+}
+```
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 8bc0a67067a..85ed31320b9 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -60,7 +60,7 @@ Parameters:
Shows information about a single merge request.
```
-GET /projects/:id/merge_request/:merge_request_id
+GET /projects/:id/merge_requests/:merge_request_id
```
Parameters:
@@ -105,7 +105,7 @@ Parameters:
Get a list of merge request commits.
```
-GET /projects/:id/merge_request/:merge_request_id/commits
+GET /projects/:id/merge_requests/:merge_request_id/commits
```
Parameters:
@@ -142,7 +142,7 @@ Parameters:
Shows information about the merge request including its files and changes.
```
-GET /projects/:id/merge_request/:merge_request_id/changes
+GET /projects/:id/merge_requests/:merge_request_id/changes
```
Parameters:
@@ -264,7 +264,7 @@ If an error occurs, an error number and a message explaining the reason is retur
Updates an existing merge request. You can change the target branch, title, or even close the MR.
```
-PUT /projects/:id/merge_request/:merge_request_id
+PUT /projects/:id/merge_requests/:merge_request_id
```
Parameters:
@@ -323,7 +323,7 @@ If merge request is already merged or closed - you get 405 and error message 'Me
If you don't have permissions to accept this merge request - you'll get a 401
```
-PUT /projects/:id/merge_request/:merge_request_id/merge
+PUT /projects/:id/merge_requests/:merge_request_id/merge
```
Parameters:
@@ -373,7 +373,7 @@ If the merge request is already merged or closed - you get 405 and error message
In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error.
```
-PUT /projects/:id/merge_request/:merge_request_id/cancel_merge_when_build_succeeds
+PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_build_succeeds
```
Parameters:
@@ -409,66 +409,6 @@ Parameters:
}
```
-## Post comment to MR
-
-Adds a comment to a merge request.
-
-```
-POST /projects/:id/merge_request/:merge_request_id/comments
-```
-
-Parameters:
-
-- `id` (required) - The ID of a project
-- `merge_request_id` (required) - ID of merge request
-- `note` (required) - Text of comment
-
-```json
-{
- "note": "text1"
-}
-```
-
-## Get the comments on a MR
-
-Gets all the comments associated with a merge request.
-
-```
-GET /projects/:id/merge_request/:merge_request_id/comments
-```
-
-Parameters:
-
-- `id` (required) - The ID of a project
-- `merge_request_id` (required) - ID of merge request
-
-```json
-[
- {
- "note": "this is the 1st comment on the 2merge merge request",
- "author": {
- "id": 11,
- "username": "admin",
- "email": "admin@example.com",
- "name": "Administrator",
- "state": "active",
- "created_at": "2014-03-06T08:17:35.000Z"
- }
- },
- {
- "note": "Status changed to closed",
- "author": {
- "id": 11,
- "username": "admin",
- "email": "admin@example.com",
- "name": "Administrator",
- "state": "active",
- "created_at": "2014-03-06T08:17:35.000Z"
- }
- }
-]
-```
-
## Comments on merge requets
-Comments are done via the notes resource.
+Comments are done via the [notes](notes.md) resource.
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index 7b3238441f6..42d9ce3d391 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -1,13 +1,29 @@
# Namespaces
+Usernames and groupnames fall under a special category called namespaces.
+
+For users and groups supported API calls see the [users](users.md) and
+[groups](groups.md) documentation respectively.
+
+[Pagination](README.md#pagination) is used.
+
## List namespaces
-Get a list of namespaces. (As user: my namespaces, as admin: all namespaces)
+Get a list of the namespaces of the authenticated user. If the user is an
+administrator, a list of all namespaces in the GitLab instance is shown.
```
GET /namespaces
```
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces
+```
+
+Example response:
+
```json
[
{
@@ -23,22 +39,32 @@ GET /namespaces
]
```
-You can search for namespaces by name or path, see below.
-
## Search for namespace
-Get all namespaces that match your string in their name or path.
+Get all namespaces that match a string in their name or path.
```
GET /namespaces?search=foobar
```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `search` | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
+
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter
+```
+
+Example response:
+
```json
[
{
- "id": 1,
- "path": "user1",
- "kind": "user"
+ "id": 4,
+ "path": "twitter",
+ "kind": "group"
}
]
```
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 241229221db..3f372c955d2 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -29,6 +29,7 @@ GET /projects
Parameters:
- `archived` (optional) - if passed, limit by archived status
+- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private`
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
@@ -152,6 +153,7 @@ GET /projects/owned
Parameters:
- `archived` (optional) - if passed, limit by archived status
+- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private`
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
@@ -167,6 +169,7 @@ GET /projects/starred
Parameters:
- `archived` (optional) - if passed, limit by archived status
+- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private`
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
@@ -182,6 +185,7 @@ GET /projects/all
Parameters:
- `archived` (optional) - if passed, limit by archived status
+- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private`
- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at`
- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc`
- `search` (optional) - Return list of authorized projects according to a search criteria
diff --git a/doc/api/settings.md b/doc/api/settings.md
index 96867c67915..001de76c7af 100644
--- a/doc/api/settings.md
+++ b/doc/api/settings.md
@@ -1,67 +1,77 @@
# Application settings
-This API allows you to read and modify GitLab instance application settings.
+These API calls allow you to read and modify GitLab instance application
+settings as appear in `/admin/application_settings`. You have to be an
+administrator in order to perform this action.
+## Get current application settings
-## Get current application settings:
+List the current application settings of the GitLab instance.
```
GET /application/settings
```
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings
+```
+
+Example response:
+
```json
{
- "id": 1,
- "default_projects_limit": 10,
- "signup_enabled": true,
- "signin_enabled": true,
- "gravatar_enabled": true,
- "sign_in_text": "",
- "created_at": "2015-06-12T15:51:55.432Z",
- "updated_at": "2015-06-30T13:22:42.210Z",
- "home_page_url": "",
- "default_branch_protection": 2,
- "twitter_sharing_enabled": true,
- "restricted_visibility_levels": [],
- "max_attachment_size": 10,
- "session_expire_delay": 10080,
- "default_project_visibility": 0,
- "default_snippet_visibility": 0,
- "restricted_signup_domains": [],
- "user_oauth_applications": true,
- "after_sign_out_path": ""
+ "default_projects_limit" : 10,
+ "signup_enabled" : true,
+ "id" : 1,
+ "default_branch_protection" : 2,
+ "restricted_visibility_levels" : [],
+ "signin_enabled" : true,
+ "twitter_sharing_enabled" : true,
+ "after_sign_out_path" : null,
+ "max_attachment_size" : 10,
+ "user_oauth_applications" : true,
+ "updated_at" : "2016-01-04T15:44:55.176Z",
+ "session_expire_delay" : 10080,
+ "home_page_url" : null,
+ "default_snippet_visibility" : 0,
+ "restricted_signup_domains" : [],
+ "created_at" : "2016-01-04T15:44:55.176Z",
+ "default_project_visibility" : 0,
+ "gravatar_enabled" : true,
+ "sign_in_text" : null
}
```
-## Change application settings:
-
-
+## Change application settings
```
PUT /application/settings
```
-Parameters:
-
-- `default_projects_limit` - project limit per user
-- `signup_enabled` - enable registration
-- `signin_enabled` - enable login via GitLab account
-- `gravatar_enabled` - enable gravatar
-- `sign_in_text` - text on login page
-- `home_page_url` - redirect to this URL when not logged in
-- `default_branch_protection` - determine if developers can push to master
-- `twitter_sharing_enabled` - allow users to share project creation in twitter
-- `restricted_visibility_levels` - restrict certain visibility levels
-- `max_attachment_size` - limit attachment size
-- `session_expire_delay` - session lifetime
-- `default_project_visibility` - what visibility level new project receives
-- `default_snippet_visibility` - what visibility level new snippet receives
-- `restricted_signup_domains` - force people to use only corporate emails for signup
-- `user_oauth_applications` - allow users to create oauth applications
-- `after_sign_out_path` - where redirect user after logout
+| Attribute | Type | Required | Description |
+| --------- | ---- | :------: | ----------- |
+| `default_projects_limit` | integer | no | Project limit per user. Default is `10` |
+| `signup_enabled` | boolean | no | Enable registration. Default is `true`. |
+| `signin_enabled` | boolean | no | Enable login via a GitLab account. Default is `true`. |
+| `gravatar_enabled` | boolean | no | Enable Gravatar |
+| `sign_in_text` | string | no | Text on login page |
+| `home_page_url` | string | no | Redirect to this URL when not logged in |
+| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `1`. |
+| `twitter_sharing_enabled` | boolean | no | Allow users to share project creation on Twitter |
+| `restricted_visibility_levels` | array of integers | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is null which means there is no restriction. |
+| `max_attachment_size` | integer | no | Limit attachment size in MB |
+| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes |
+| `default_project_visibility` | integer | no | What visibility level new projects receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.|
+| `default_snippet_visibility` | integer | no | What visibility level new snippets receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.|
+| `restricted_signup_domains` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. |
+| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider |
+| `after_sign_out_path` | string | no | Where to redirect users after logout |
-All parameters are optional. You can send only one that you want to change.
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings?signup_enabled=false&default_project_visibility=1
+```
+Example response:
```json
{
@@ -79,7 +89,7 @@ All parameters are optional. You can send only one that you want to change.
"restricted_visibility_levels": [],
"max_attachment_size": 10,
"session_expire_delay": 10080,
- "default_project_visibility": 0,
+ "default_project_visibility": 1,
"default_snippet_visibility": 0,
"restricted_signup_domains": [],
"user_oauth_applications": true,
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index f9637d8a6c4..dc036d7e27f 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -1,40 +1,71 @@
# System hooks
-All methods require admin authorization.
+All methods require administrator authorization.
-The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks).
+The URL endpoint of the system hooks can also be configured using the UI in
+the admin area under **Hooks** (`/admin/hooks`).
+
+Read more about [system hooks](../system_hooks/system_hooks.md).
## List system hooks
-Get list of system hooks
+Get a list of all system hooks.
+
+---
```
GET /hooks
```
-Parameters:
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks
+```
-- **none**
+Example response:
```json
[
- {
- "id": 3,
- "url": "http://example.com/hook",
- "created_at": "2013-10-02T10:15:31Z"
- }
+ {
+ "id" : 1,
+ "url" : "https://gitlab.example.com/hook",
+ "created_at" : "2015-11-04T20:07:35.874Z"
+ }
]
```
-## Add new system hook hook
+## Add new system hook
+
+Add a new system hook.
+
+---
```
POST /hooks
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `url` | string | yes | The hook URL |
+
+Example request:
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook"
+```
+
+Example response:
-- `url` (required) - The hook URL
+```json
+[
+ {
+ "id" : 2,
+ "url" : "https://gitlab.example.com/hook",
+ "created_at" : "2015-11-04T20:07:35.874Z"
+ }
+]
+```
## Test system hook
@@ -42,29 +73,68 @@ Parameters:
GET /hooks/:id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the hook |
-- `id` (required) - The ID of hook
+Example request:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
+```
+
+Example response:
```json
{
- "event_name": "project_create",
- "name": "Ruby",
- "path": "ruby",
- "project_id": 1,
- "owner_name": "Someone",
- "owner_email": "example@gitlabhq.com"
+ "project_id" : 1,
+ "owner_email" : "example@gitlabhq.com",
+ "owner_name" : "Someone",
+ "name" : "Ruby",
+ "path" : "ruby",
+ "event_name" : "project_create"
}
```
## Delete system hook
-Deletes a system hook. This is an idempotent API function and returns `200 OK` even if the hook is not available. If the hook is deleted it is also returned as JSON.
+Deletes a system hook. This is an idempotent API function and returns `200 OK`
+even if the hook is not available.
+
+If the hook is deleted, a JSON object is returned. An error is raised if the
+hook is not found.
+
+---
```
DELETE /hooks/:id
```
-Parameters:
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of the hook |
+
+Example request:
-- `id` (required) - The ID of hook
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
+```
+
+Example response:
+
+```json
+{
+ "note_events" : false,
+ "project_id" : null,
+ "enable_ssl_verification" : true,
+ "url" : "https://gitlab.example.com/hook",
+ "updated_at" : "2015-11-04T20:12:15.931Z",
+ "issues_events" : false,
+ "merge_requests_events" : false,
+ "created_at" : "2015-11-04T20:12:15.931Z",
+ "service_id" : null,
+ "id" : 2,
+ "push_events" : true,
+ "tag_push_events" : false
+}
+```
View Lorry Controller Status