Documentation | 2025.1

# Search: Swarm search

## Search Redis cache

### Summary

Search the Redis cache for users, groups, projects, files, and file content.

GET /api/v11/search?term=<term>&context=user,group,project,filePath,fileContent

### Description

Search the Redis cache for:

- userids and full names

- groupids and group names

- projectids and project names

- file path

- file content (only if Helix Search is configured for Swarm, see Search)

Results are returned in alphabetical order and the search is case insensitive.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
term | Specifies the characters to search for. Searches are case insensitive. | string | path | Yes
context | Limit the search results, valid context values are user, group, project, filePath, and fileContent (see note below). Separate context values with a comma (,). If Helix Search is configured for Swarm, see Search: The filePath search is carried out by Helix Search and not Swarm. This improves the performance of the search request. The fileContent search is available and carried out by Helix Search. | string | path | Yes
starts_with_only | Options are: true: searches for users/groups that start with the search term. This results in a faster search than when this parameter is set to false. false: searches for the term anywhere in users/groups. This is the search used if starts_with_only is not included in the request. | boolean | path | No
limit | Limit the combined maximum number of search results returned for users and groups. Search results are balanced across the contexts requested and will never return more results than the specified limit. Examples: based on a search that results in 8 user matches and 30 group matches before the limit is applied: limit=7 and context=user: search result is limited to 7 users. limit=6 and context=user,group: search result is limited to 3 users and 3 groups. An even limit value splits the search result limit evenly between the specified contexts. limit=7 and context=user,group: search result is limited to 4 users and 3 groups. An odd limit value splits the search result limit unevenly between the specified contexts with the higher number applied to the first context in the list. limit=20 and context=user,group, search result is limited to 8 users and 12 groups. Search results are not limited when the limit parameter is excluded from the request. | integer | path | No
ignoreExcludeList | Options are: true: the user_exclude_list and group_exclude_list filters are ignored and are not applied to the search results. false: applies the user_exclude_list and group_exclude_list filters to the search results. This is the search used if ignoreExcludeList is not included in the request. | boolean | path | No

### Example usage

#### Search users, groups, and projects starting with "jo" with a limit of 4 results returned

Search users and groups starting with "jo" with a limit of 4 results returned.

curl -u "username:ticket" "https://myswarm-url/api/v11/search?starts_with_only=true&term=jo&context=user,group,project&limit=4"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "user": {
          "results":[
            {
              "id": "joakly",
              "name": "Jane Oakly"
            },
            {
              "id": "jsmith",
              "name": "John Smith"
            }
          ]
        },
        "group": {
          "results": [
            {
              "id": "jogd",
              "name": "JOGD"
            }
          ]
        },
        "project": {
          "results": [
            {
              "id": "johns-project",
              "name": "Johns Project"
            }
          ]
        },
        "limit": 4
      }
    }

#### Search groups for "admin" anywhere in group names and groupids

Search for "admin" anywhere in group names and groupids with no limit on the number of results returned by the search.

curl -u "username:ticket" "https://myswarm-url/api/v11/search?context=group&term=admin"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "group": {
          "results": [
            {
              "id": "swarm-admin",
              "name": "Swarm-admin"
            },
            {
              "id": "jplugin-admin",
              "name": "JPlugin-Admin"
            },
            {
              "id": "administrators",
              "name": "Administrators"
            },
            {
              "id": "sysadmins",
              "name": "Sysadmins"
            }
          ]
        }
      }
    }

#### Search files for "myfile" anywhere in file path

Search for "myfile" anywhere in file path with no limit on the number of results returned by the search.

curl -u "username:ticket" "https://myswarm-url/api/v11/search?context=filePath&term=myfile"

The response returned depends on whether Helix Search is configured for Swarm or not:

- If Helix Search is not configured for Swarm, Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "filePath": {
          "filesCount": 6,
          "maxScore": 100,
          "results": [
            {
              "type": "file",
              "change": null,
              "depotFile": "//depot/thisIsMyFile.txt",
              "fileName": "thisIsMyFile.txt",
              "action": null,
              "fileType": null,
              "rev": null,
              "fileSize": false
            },
            ....
            <results for other files formatted as above>
            ....
          ],
        }
      }
    },

- If Helix Search is configured for Swarm, Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "filePath": {
          "filesCount": 6,
          "maxScore": 100,
          "results": [
            {
              "type": "revision",
              "change": 10032,
              "depotFile": "//depot/thisIsMyFile.txt",
              "fileName": "thisIsMyFile.txt",
              "action": "branch",
              "fileType": "text",
              "rev": 1,
              "fileSize": 1714
            },
            ....
            <results for other files formatted as above>
            ....
          ],
        }
      }
    },

#### Search file content for "foobar" anywhere in the file content

The file content search is only available if Helix Search is configured for Swarm, see Search

Search for "foobar" anywhere in file content with no limit on the number of results returned by the search.

curl -u "username:ticket" "https://myswarm-url/api/v11/search?context=fileContent&term=foobar"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "fileContent": {
          "filesCount": 6,
          "maxScore": null,
          "results": [
            {
              "type": "content",
              "change": 12250,
              "depotFile": "//depot/jim",
              "fileName": "jim",
              "action": 'edit',
              "fileType": 'text',
              "rev": 3,
              "fileSize": 703
            },
            ....
            <results for other files formatted as above>
            ....
          ],
        }
      }
    },

#### If a request fails

<error code>:

422 Parameter not specified or invalid, the error message in the response contains the error details.

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

Your search for returned results