2020-07-30 12:09:33 +00:00
---
stage: Create
group: Source Code
2021-12-28 21:16:11 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-30 12:09:33 +00:00
---
2021-02-09 18:09:59 +00:00
# Search API **(FREE)**
2018-01-31 14:59:59 +00:00
2021-12-28 21:16:11 +00:00
> [Feature flag `search_filter_by_confidential` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/244923) in GitLab 13.6.
2018-02-07 10:52:51 +00:00
2018-01-31 14:59:59 +00:00
Every API call to search must be authenticated.
2021-03-03 00:10:50 +00:00
## Advanced Search API
2018-01-31 14:59:59 +00:00
Search globally across the GitLab instance.
2020-02-28 03:09:04 +00:00
```plaintext
2018-01-31 14:59:59 +00:00
GET /search
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `scope` | string | yes | The scope to search in |
| `search` | string | yes | The search query |
2020-09-15 12:09:30 +00:00
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
2020-10-23 03:08:37 +00:00
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
2021-03-08 18:09:12 +00:00
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
Search the expression in the specified scope. These scopes are supported: `projects` , `issues` , `merge_requests` , `milestones` , `snippet_titles` , `users` .
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
If Elasticsearch is enabled additional scopes available are `blobs` , `wiki_blobs` , `notes` , and `commits` . Find more about [the feature ](../integration/elasticsearch.md ). ** (PREMIUM)**
2019-06-06 07:57:39 +00:00
2018-01-31 14:59:59 +00:00
The response depends on the requested scope.
2022-06-14 00:08:43 +00:00
### Scope: `projects`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=projects& search=flight"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 6,
"description": "Nobis sed ipsam vero quod cupiditate veritatis hic.",
"name": "Flight",
"name_with_namespace": "Twitter / Flight",
"path": "flight",
"path_with_namespace": "twitter/flight",
"created_at": "2017-09-05T07:58:01.621Z",
"default_branch": "master",
2021-06-07 18:10:23 +00:00
"tag_list":[], //deprecated, use `topics` instead
"topics":[],
2018-01-31 14:59:59 +00:00
"ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git",
"http_url_to_repo": "http://localhost:3000/twitter/flight.git",
"web_url": "http://localhost:3000/twitter/flight",
"avatar_url": null,
"star_count": 0,
"forks_count": 0,
"last_activity_at": "2018-01-31T09:56:30.902Z"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `issues`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=issues& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 83,
"iid": 1,
"project_id": 12,
"title": "Add file",
"description": "Add first file",
"state": "opened",
"created_at": "2018-01-24T06:02:15.514Z",
"updated_at": "2018-02-06T12:36:23.263Z",
"closed_at": null,
"labels":[],
"milestone": null,
"assignees": [{
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
}],
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
},
"user_notes_count": 0,
"upvotes": 0,
"downvotes": 0,
"due_date": null,
"confidential": false,
"discussion_locked": null,
"web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `merge_requests`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=merge_requests& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 56,
"iid": 8,
"project_id": 6,
"title": "Add first file",
"description": "This is a test MR to add file",
"state": "opened",
"created_at": "2018-01-22T14:21:50.830Z",
"updated_at": "2018-02-06T12:40:33.295Z",
"target_branch": "master",
"source_branch": "jaja-test",
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 5,
"name": "Jacquelyn Kutch",
"username": "abigail",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80& d=identicon",
"web_url": "http://localhost:3000/abigail"
},
"source_project_id": 6,
"target_project_id": 6,
"labels": [
"ruby",
"tests"
],
2021-06-10 03:10:01 +00:00
"draft": false,
2018-01-31 14:59:59 +00:00
"work_in_progress": false,
"milestone": {
"id": 13,
"iid": 3,
"project_id": 6,
"title": "v2.0",
"description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
"state": "active",
"created_at": "2017-09-05T07:58:29.099Z",
"updated_at": "2017-09-05T07:58:29.099Z",
"due_date": null,
"start_date": null
},
"merge_when_pipeline_succeeds": false,
"merge_status": "can_be_merged",
"sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
"merge_commit_sha": null,
2019-11-05 21:07:46 +00:00
"squash_commit_sha": null,
2018-01-31 14:59:59 +00:00
"user_notes_count": 0,
"discussion_locked": null,
"should_remove_source_branch": null,
"force_remove_source_branch": true,
"web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `milestones`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=milestones& search=release"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 44,
"iid": 1,
"project_id": 12,
"title": "next release",
"description": "Next release milestone",
"state": "active",
"created_at": "2018-02-06T12:43:39.271Z",
"updated_at": "2018-02-06T12:44:01.298Z",
"due_date": "2018-04-18",
"start_date": "2018-02-04"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `snippet_titles`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=snippet_titles& search=sample"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 50,
"title": "Sample file",
"file_name": "file.rb",
"description": "Simple ruby file",
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"updated_at": "2018-02-06T12:49:29.104Z",
"created_at": "2017-11-28T08:20:18.071Z",
"project_id": 9,
"web_url": "http://localhost:3000/root/jira-test/snippets/50"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `wiki_blobs` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
2019-06-25 04:34:55 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2019-06-06 07:57:39 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=wiki_blobs& search=bye"
2019-06-06 07:57:39 +00:00
```
Example response:
```json
[
{
"basename": "home",
"data": "hello\n\nand bye\n\nend",
2019-10-24 00:07:18 +00:00
"path": "home.md",
2019-06-06 07:57:39 +00:00
"filename": "home.md",
"id": null,
"ref": "master",
"startline": 5,
"project_id": 6
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2021-02-03 15:09:24 +00:00
### Scope: commits **(PREMIUM)**
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=commits& search=bye"
2019-06-06 07:57:39 +00:00
```
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
}
]
```
2021-02-03 15:09:24 +00:00
### Scope: blobs **(PREMIUM)**
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
Filters are available for this scope:
2019-06-25 04:34:55 +00:00
2019-06-06 07:57:39 +00:00
- filename
- path
- extension
2022-02-22 00:14:20 +00:00
To use a filter, include it in your query. For example: `a query filename:some_name*` .
2019-06-06 07:57:39 +00:00
You may use wildcards (`*`) to use glob matching.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=blobs& search=installation"
2019-06-06 07:57:39 +00:00
```
Example response:
```json
[
{
"basename": "README",
"data": "```\n\n## Installation\n\nQuick start using the [pre-built",
2019-10-24 00:07:18 +00:00
"path": "README.md",
2019-06-06 07:57:39 +00:00
"filename": "README.md",
"id": null,
"ref": "master",
"startline": 46,
"project_id": 6
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2021-02-03 15:09:24 +00:00
### Scope: notes **(PREMIUM)**
> Moved to GitLab Premium in 13.9.
2020-09-21 03:09:25 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=notes& search=maxime"
```
Example response:
```json
[
{
"id": 191,
"body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
"attachment": null,
"author": {
"id": 23,
"name": "User 1",
"username": "user1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80& d=identicon",
"web_url": "http://localhost:3000/user1"
},
"created_at": "2017-09-05T08:01:32.068Z",
"updated_at": "2017-09-05T08:01:32.068Z",
"system": false,
"noteable_id": 22,
"noteable_type": "Issue",
"noteable_iid": 2
}
]
```
2018-09-17 12:54:32 +00:00
### Scope: users
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/search?scope=users& search=doe"
2018-09-17 12:54:32 +00:00
```
Example response:
```json
[
{
"id": 1,
"name": "John Doe1",
"username": "user1",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80& d=identicon",
"web_url": "http://localhost/user1"
}
]
```
2018-01-31 14:59:59 +00:00
## Group Search API
2022-02-22 00:14:20 +00:00
Search in the specified group.
2018-01-31 14:59:59 +00:00
2021-03-08 18:09:12 +00:00
If a user is not a member of a group and the group is private, a `GET` request on that group results in a `404` status code.
2018-01-31 14:59:59 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2018-03-14 15:49:21 +00:00
GET /groups/:id/search
2018-01-31 14:59:59 +00:00
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the group ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2018-01-31 14:59:59 +00:00
| `scope` | string | yes | The scope to search in |
| `search` | string | yes | The search query |
2020-09-15 12:09:30 +00:00
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
2020-10-23 03:08:37 +00:00
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
2021-03-08 18:09:12 +00:00
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
Search the expression in the specified scope. These scopes are supported: `projects` , `issues` , `merge_requests` , `milestones` , `users` .
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
If Elasticsearch is enabled additional scopes available are `blobs` , `wiki_blobs` , `notes` , and `commits` . Find more about [the feature ](../integration/elasticsearch.md ). ** (PREMIUM)**
2019-06-06 07:57:39 +00:00
2018-01-31 14:59:59 +00:00
The response depends on the requested scope.
2022-06-14 00:08:43 +00:00
### Scope: `projects`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/3/search?scope=projects& search=flight"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 6,
"description": "Nobis sed ipsam vero quod cupiditate veritatis hic.",
"name": "Flight",
"name_with_namespace": "Twitter / Flight",
"path": "flight",
"path_with_namespace": "twitter/flight",
"created_at": "2017-09-05T07:58:01.621Z",
"default_branch": "master",
2021-06-07 18:10:23 +00:00
"tag_list":[], //deprecated, use `topics` instead
"topics":[],
2018-01-31 14:59:59 +00:00
"ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git",
"http_url_to_repo": "http://localhost:3000/twitter/flight.git",
"web_url": "http://localhost:3000/twitter/flight",
"avatar_url": null,
"star_count": 0,
"forks_count": 0,
"last_activity_at": "2018-01-31T09:56:30.902Z"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `issues`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/3/search?scope=issues& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 83,
"iid": 1,
"project_id": 12,
"title": "Add file",
"description": "Add first file",
"state": "opened",
"created_at": "2018-01-24T06:02:15.514Z",
"updated_at": "2018-02-06T12:36:23.263Z",
"closed_at": null,
"labels":[],
"milestone": null,
"assignees": [{
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
}],
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
},
"user_notes_count": 0,
"upvotes": 0,
"downvotes": 0,
"due_date": null,
"confidential": false,
"discussion_locked": null,
"web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `merge_requests`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/3/search?scope=merge_requests& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 56,
"iid": 8,
"project_id": 6,
"title": "Add first file",
"description": "This is a test MR to add file",
"state": "opened",
"created_at": "2018-01-22T14:21:50.830Z",
"updated_at": "2018-02-06T12:40:33.295Z",
"target_branch": "master",
"source_branch": "jaja-test",
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 5,
"name": "Jacquelyn Kutch",
"username": "abigail",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80& d=identicon",
"web_url": "http://localhost:3000/abigail"
},
"source_project_id": 6,
"target_project_id": 6,
"labels": [
"ruby",
"tests"
],
2021-06-10 03:10:01 +00:00
"draft": false,
2018-01-31 14:59:59 +00:00
"work_in_progress": false,
"milestone": {
"id": 13,
"iid": 3,
"project_id": 6,
"title": "v2.0",
"description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
"state": "active",
"created_at": "2017-09-05T07:58:29.099Z",
"updated_at": "2017-09-05T07:58:29.099Z",
"due_date": null,
"start_date": null
},
"merge_when_pipeline_succeeds": false,
"merge_status": "can_be_merged",
"sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
"merge_commit_sha": null,
2019-11-05 21:07:46 +00:00
"squash_commit_sha": null,
2018-01-31 14:59:59 +00:00
"user_notes_count": 0,
"discussion_locked": null,
"should_remove_source_branch": null,
"force_remove_source_branch": true,
"web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `milestones`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/3/search?scope=milestones& search=release"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 44,
"iid": 1,
"project_id": 12,
"title": "next release",
"description": "Next release milestone",
"state": "active",
"created_at": "2018-02-06T12:43:39.271Z",
"updated_at": "2018-02-06T12:44:01.298Z",
"due_date": "2018-04-18",
"start_date": "2018-02-04"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `wiki_blobs` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs& search=bye"
2019-06-06 07:57:39 +00:00
```
Example response:
```json
[
{
"basename": "home",
"data": "hello\n\nand bye\n\nend",
2019-10-24 00:07:18 +00:00
"path": "home.md",
2019-06-06 07:57:39 +00:00
"filename": "home.md",
"id": null,
"ref": "master",
"startline": 5,
"project_id": 6
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `commits` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/6/search?scope=commits& search=bye"
2019-06-06 07:57:39 +00:00
```
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
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `blobs` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2019-06-06 07:57:39 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
Filters are available for this scope:
2019-06-25 04:34:55 +00:00
2019-06-06 07:57:39 +00:00
- filename
- path
- extension
2022-02-22 00:14:20 +00:00
To use a filter, include it in your query. For example: `a query filename:some_name*` .
2019-06-06 07:57:39 +00:00
You may use wildcards (`*`) to use glob matching.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/6/search?scope=blobs& search=installation"
2019-06-06 07:57:39 +00:00
```
Example response:
```json
[
{
"basename": "README",
"data": "```\n\n## Installation\n\nQuick start using the [pre-built",
2019-10-24 00:07:18 +00:00
"path": "README.md",
2019-06-06 07:57:39 +00:00
"filename": "README.md",
"id": null,
"ref": "master",
"startline": 46,
"project_id": 6
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `notes` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2020-09-21 03:09:25 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=notes& search=maxime"
```
Example response:
```json
[
{
"id": 191,
"body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
"attachment": null,
"author": {
"id": 23,
"name": "User 1",
"username": "user1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80& d=identicon",
"web_url": "http://localhost:3000/user1"
},
"created_at": "2017-09-05T08:01:32.068Z",
"updated_at": "2017-09-05T08:01:32.068Z",
"system": false,
"noteable_id": 22,
"noteable_type": "Issue",
"noteable_iid": 2
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `users`
2018-09-17 12:54:32 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/3/search?scope=users& search=doe"
2018-09-17 12:54:32 +00:00
```
Example response:
```json
[
{
"id": 1,
"name": "John Doe1",
"username": "user1",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80& d=identicon",
"web_url": "http://localhost/user1"
}
]
```
2018-01-31 14:59:59 +00:00
## Project Search API
2022-02-22 00:14:20 +00:00
Search in the specified project.
2018-01-31 14:59:59 +00:00
2021-03-08 18:09:12 +00:00
If a user is not a member of a project and the project is private, a `GET` request on that project results in a `404` status code.
2018-01-31 14:59:59 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2018-03-14 15:49:21 +00:00
GET /projects/:id/search
2018-01-31 14:59:59 +00:00
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2018-01-31 14:59:59 +00:00
| `scope` | string | yes | The scope to search in |
| `search` | string | yes | The search query |
2022-06-14 00:08:43 +00:00
| `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` . |
2020-09-15 12:09:30 +00:00
| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. |
2020-10-23 03:08:37 +00:00
| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. |
2021-03-08 18:09:12 +00:00
| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.|
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
Search the expression in the specified scope. These scopes are supported: `issues` , `merge_requests` , `milestones` , `notes` , `wiki_blobs` , `commits` , `blobs` , `users` .
2018-01-31 14:59:59 +00:00
The response depends on the requested scope.
2022-06-14 00:08:43 +00:00
### Scope: `issues`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/12/search?scope=issues& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 83,
"iid": 1,
"project_id": 12,
"title": "Add file",
"description": "Add first file",
"state": "opened",
"created_at": "2018-01-24T06:02:15.514Z",
"updated_at": "2018-02-06T12:36:23.263Z",
"closed_at": null,
"labels":[],
"milestone": null,
"assignees": [{
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
}],
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 20,
"name": "Ceola Deckow",
"username": "sammy.collier",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80& d=identicon",
"web_url": "http://localhost:3000/sammy.collier"
},
"user_notes_count": 0,
"upvotes": 0,
"downvotes": 0,
"due_date": null,
"confidential": false,
"discussion_locked": null,
"web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
2018-01-31 14:59:59 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `merge_requests`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=merge_requests& search=file"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 56,
"iid": 8,
"project_id": 6,
"title": "Add first file",
"description": "This is a test MR to add file",
"state": "opened",
"created_at": "2018-01-22T14:21:50.830Z",
"updated_at": "2018-02-06T12:40:33.295Z",
"target_branch": "master",
"source_branch": "jaja-test",
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
"web_url": "http://localhost:3000/root"
},
"assignee": {
"id": 5,
"name": "Jacquelyn Kutch",
"username": "abigail",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80& d=identicon",
"web_url": "http://localhost:3000/abigail"
},
"source_project_id": 6,
"target_project_id": 6,
"labels": [
"ruby",
"tests"
],
2021-06-10 03:10:01 +00:00
"draft": false,
2018-01-31 14:59:59 +00:00
"work_in_progress": false,
"milestone": {
"id": 13,
"iid": 3,
"project_id": 6,
"title": "v2.0",
"description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
"state": "active",
"created_at": "2017-09-05T07:58:29.099Z",
"updated_at": "2017-09-05T07:58:29.099Z",
"due_date": null,
"start_date": null
},
"merge_when_pipeline_succeeds": false,
"merge_status": "can_be_merged",
"sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
"merge_commit_sha": null,
2019-11-05 21:07:46 +00:00
"squash_commit_sha": null,
2018-01-31 14:59:59 +00:00
"user_notes_count": 0,
"discussion_locked": null,
"should_remove_source_branch": null,
"force_remove_source_branch": true,
"web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
}
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `milestones`
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/12/search?scope=milestones& search=release"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 44,
"iid": 1,
"project_id": 12,
"title": "next release",
"description": "Next release milestone",
"state": "active",
"created_at": "2018-02-06T12:43:39.271Z",
"updated_at": "2018-02-06T12:44:01.298Z",
"due_date": "2018-04-18",
"start_date": "2018-02-04"
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `notes` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2021-01-19 09:10:32 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=notes& search=maxime"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"id": 191,
"body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
"attachment": null,
"author": {
"id": 23,
"name": "User 1",
"username": "user1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80& d=identicon",
"web_url": "http://localhost:3000/user1"
},
"created_at": "2017-09-05T08:01:32.068Z",
"updated_at": "2017-09-05T08:01:32.068Z",
"system": false,
"noteable_id": 22,
"noteable_type": "Issue",
"noteable_iid": 2
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `wiki_blobs` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2021-01-19 09:10:32 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2018-01-31 14:59:59 +00:00
2018-12-07 08:50:23 +00:00
Filters are available for this scope:
- filename
- path
- extension
2022-02-22 00:14:20 +00:00
To use a filter, include it in your query. For example: `a query filename:some_name*` .
2018-12-07 08:50:23 +00:00
You may use wildcards (`*`) to use glob matching.
2018-12-02 21:47:33 +00:00
Wiki blobs searches are performed on both filenames and contents. Search
results:
- Found in filenames are displayed before results found in contents.
- May contain multiple matches for the same blob because the search string
2018-12-07 08:50:23 +00:00
might be found in both the filename and content, or might appear multiple
times in the content.
2018-12-02 21:47:33 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=wiki_blobs& search=bye"
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"basename": "home",
"data": "hello\n\nand bye\n\nend",
2019-10-24 00:07:18 +00:00
"path": "home.md",
2018-01-31 14:59:59 +00:00
"filename": "home.md",
"id": null,
"ref": "master",
2018-02-13 12:41:35 +00:00
"startline": 5,
"project_id": 6
2018-01-31 14:59:59 +00:00
}
]
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` are intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `commits` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2021-01-19 09:10:32 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2018-01-31 14:59:59 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=commits& search=bye"
2018-01-31 14:59:59 +00:00
```
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",
2018-02-13 12:41:35 +00:00
"committed_date": "2013-02-18T22:02:54.000Z",
"project_id": 6
2018-01-31 14:59:59 +00:00
}
]
```
2022-06-14 00:08:43 +00:00
### Scope: `blobs` **(PREMIUM)**
2021-02-03 15:09:24 +00:00
> Moved to GitLab Premium in 13.9.
2021-01-19 09:10:32 +00:00
This scope is available only if [Elasticsearch ](../integration/elasticsearch.md ) is enabled.
2018-01-31 14:59:59 +00:00
2018-06-07 00:14:10 +00:00
Filters are available for this scope:
2018-12-07 08:50:23 +00:00
2018-06-07 00:14:10 +00:00
- filename
- path
- extension
2022-02-22 00:14:20 +00:00
To use a filter, include it in your query. For example: `a query filename:some_name*` .
2018-12-07 08:50:23 +00:00
You may use wildcards (`*`) to use glob matching.
2018-06-07 00:14:10 +00:00
2018-12-02 21:47:33 +00:00
Blobs searches are performed on both filenames and contents. Search results:
- Found in filenames are displayed before results found in contents.
- May contain multiple matches for the same blob because the search string
2018-12-07 08:50:23 +00:00
might be found in both the filename and content, or might appear multiple
times in the content.
2018-06-07 00:14:10 +00:00
2020-01-30 15:09:15 +00:00
```shell
2021-09-23 22:34:10 +00:00
curl --request GET --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/6/search?scope=blobs& search=keyword%20filename:*.py
2018-01-31 14:59:59 +00:00
```
Example response:
```json
[
{
"basename": "README",
"data": "```\n\n## Installation\n\nQuick start using the [pre-built",
2019-10-24 00:07:18 +00:00
"path": "README.md",
2018-01-31 14:59:59 +00:00
"filename": "README.md",
"id": null,
2021-09-23 22:34:10 +00:00
"ref": "master",
2018-02-13 12:41:35 +00:00
"startline": 46,
"project_id": 6
2018-01-31 14:59:59 +00:00
}
]
```
2018-02-07 10:52:51 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2021-03-08 18:09:12 +00:00
`filename` is deprecated in favor of `path` . Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521 ](https://gitlab.com/gitlab-org/gitlab/-/issues/34521 ).
2019-10-24 00:07:18 +00:00
2022-06-14 00:08:43 +00:00
### Scope: `users`
2018-09-17 12:54:32 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/6/search?scope=users& search=doe"
2018-09-17 12:54:32 +00:00
```
Example response:
```json
[
{
"id": 1,
"name": "John Doe1",
"username": "user1",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80& d=identicon",
"web_url": "http://localhost/user1"
}
]
```