[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides
the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`.
The API uses JSON to serialize data. You don't need to specify `.json` at the
The API uses JSON to serialize data. You don't need to specify `.json` at the
end of an API URL.
end of an API URL.
All of the API endpoints that use the `POST`, `PUT` or `PATCH` method support params in the request body, with `Content-Type``application/x-www-form-urlencoded`, `multipart/form-data` or `application/json`.
## Authentication
## Authentication
Most API requests require authentication, or will only return public data when
Most API requests require authentication, or will only return public data when
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. |
| `job_id` | integer | yes | ID of a job. |
| `job_token`**[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. |
| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. |
| `job` | string | yes | The name of the job. |
| `job` | string | yes | The name of the job. |
| `job_token`**[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*`**[PREMIUM]** |
Example request:
Example request:
...
@@ -256,6 +257,7 @@ Parameters:
...
@@ -256,6 +257,7 @@ Parameters:
| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** |
NOTE: **Note:**
NOTE: **Note:**
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
| `value` | string | yes | The `value` of a variable |
| `value` | string | yes | The `value` of a variable |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `protected` | boolean | no | Whether the variable is protected |
| `protected` | boolean | no | Whether the variable is protected |
| `masked` | boolean | no | Whether the variable is masked |
| `masked` | boolean | no | Whether the variable is masked |
| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** |
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `key` | string | yes | The `key` of a variable |
| `key` | string | yes | The `key` of a variable |
| `value` | string | yes | The `value` of a variable |
| `value` | string | yes | The `value` of a variable |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
| `protected` | boolean | no | Whether the variable is protected |
| `protected` | boolean | no | Whether the variable is protected |
| `masked` | boolean | no | Whether the variable is masked |
| `masked` | boolean | no | Whether the variable is masked |
| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** |
```
```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users.
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users.
If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
The response depends on the requested scope.
The response depends on the requested scope.
### Scope: projects
### Scope: projects
...
@@ -281,6 +283,98 @@ Example response:
...
@@ -281,6 +283,98 @@ Example response:
]
]
```
```
### Scope: wiki_blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye
```
Example response:
```json
[
{
"basename":"home",
"data":"hello\n\nand bye\n\nend",
"filename":"home.md",
"id":null,
"ref":"master",
"startline":5,
"project_id":6
}
]
```
### Scope: commits **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=commits&search=bye
```
Example response:
```json
[
{
"id":"4109c2d872d5fdb1ed057400d103766aaea97f98",
"short_id":"4109c2d8",
"title":"goodbye $.browser",
"created_at":"2013-02-18T22:02:54.000Z",
"parent_ids":[
"59d05353ab575bcc2aa958fe1782e93297de64c9"
],
"message":"goodbye $.browser\n",
"author_name":"angus croll",
"author_email":"anguscroll@gmail.com",
"authored_date":"2013-02-18T22:02:54.000Z",
"committer_name":"angus croll",
"committer_email":"anguscroll@gmail.com",
"committed_date":"2013-02-18T22:02:54.000Z",
"project_id":6
}
]
```
### Scope: blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
Filters are available for this scope:
- filename
- path
- extension
to use a filter simply include it in your query like so: `a query filename:some_name*`.
You may use wildcards (`*`) to use glob matching.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=blobs&search=installation
```
Example response:
```json
[
{
"basename":"README",
"data":"```\n\n## Installation\n\nQuick start using the [pre-built",
"filename":"README.md",
"id":null,
"ref":"master",
"startline":46,
"project_id":6
}
]
```
### Scope: users
### Scope: users
```bash
```bash
...
@@ -320,6 +414,8 @@ GET /groups/:id/search
...
@@ -320,6 +414,8 @@ GET /groups/:id/search
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users.
If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]**
The response depends on the requested scope.
The response depends on the requested scope.
### Scope: projects
### Scope: projects
...
@@ -520,6 +616,98 @@ Example response:
...
@@ -520,6 +616,98 @@ Example response:
]
]
```
```
### Scope: wiki_blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs&search=bye
```
Example response:
```json
[
{
"basename":"home",
"data":"hello\n\nand bye\n\nend",
"filename":"home.md",
"id":null,
"ref":"master",
"startline":5,
"project_id":6
}
]
```
### Scope: commits **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=commits&search=bye
```
Example response:
```json
[
{
"id":"4109c2d872d5fdb1ed057400d103766aaea97f98",
"short_id":"4109c2d8",
"title":"goodbye $.browser",
"created_at":"2013-02-18T22:02:54.000Z",
"parent_ids":[
"59d05353ab575bcc2aa958fe1782e93297de64c9"
],
"message":"goodbye $.browser\n",
"author_name":"angus croll",
"author_email":"anguscroll@gmail.com",
"authored_date":"2013-02-18T22:02:54.000Z",
"committer_name":"angus croll",
"committer_email":"anguscroll@gmail.com",
"committed_date":"2013-02-18T22:02:54.000Z",
"project_id":6
}
]
```
### Scope: blobs **[STARTER]**
This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled.
Filters are available for this scope:
- filename
- path
- extension
to use a filter simply include it in your query like so: `a query filename:some_name*`.
You may use wildcards (`*`) to use glob matching.
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=blobs&search=installation
```
Example response:
```json
[
{
"basename":"README",
"data":"```\n\n## Installation\n\nQuick start using the [pre-built",
"filename":"README.md",
"id":null,
"ref":"master",
"startline":46,
"project_id":6
}
]
```
### Scope: users
### Scope: users
```bash
```bash
...
@@ -556,7 +744,6 @@ GET /projects/:id/search
...
@@ -556,7 +744,6 @@ GET /projects/:id/search
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `scope` | string | yes | The scope to search in |
| `scope` | string | yes | The scope to search in |
| `search` | string | yes | The search query |
| `search` | string | yes | The search query |
| `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. |
Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users.
Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users.
...
@@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results:
...
@@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results:
times in the content.
times in the content.
```bash
```bash
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation&ref=feature
curl --request GET --header"PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation
```
```
Example response:
Example response:
...
@@ -864,7 +1051,7 @@ Example response:
...
@@ -864,7 +1051,7 @@ Example response:
"data":"```\n\n## Installation\n\nQuick start using the [pre-built",
"data":"```\n\n## Installation\n\nQuick start using the [pre-built",
