github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/api-docs/search.mdx (about) 1 --- 2 layout: api 3 page_title: Search - HTTP API 4 sidebar_title: Search 5 description: The /search endpoint is used to search for Nomad objects 6 --- 7 8 # Search HTTP API 9 10 The `/search` endpoint returns matches for a given prefix and context, where a 11 context can be jobs, allocations, evaluations, nodes, deployments, plugins, 12 or volumes. When using Nomad Enterprise, the allowed contexts include quotas 13 and namespaces. Additionally, a prefix can be searched for within every context. 14 15 | Method | Path | Produces | 16 | ------ | ------------ | ------------------ | 17 | `POST` | `/v1/search` | `application/json` | 18 19 The table below shows this endpoint's support for 20 [blocking queries](/api-docs#blocking-queries) and 21 [required ACLs](/api-docs#acls). 22 23 | Blocking Queries | ACL Required | 24 | ---------------- | -------------------------------- | 25 | `NO` | `node:read, namespace:read-jobs` | 26 27 When ACLs are enabled, requests must have a token valid for `node:read` or 28 `namespace:read-jobs` roles. If the token is only valid for `node:read`, then 29 job related results will not be returned. If the token is only valid for 30 `namespace:read-jobs`, then node results will not be returned. 31 32 ### Parameters 33 34 - `Prefix` `(string: <required>)` - Specifies the identifier against which 35 matches will be found. For example, if the given prefix were "a", potential 36 matches might be "abcd", or "aabb". 37 - `Context` `(string: <required>)` - Defines the scope in which a search for a 38 prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes", 39 "deployment", "plugins", "volumes" or "all", where "all" means every 40 context will be searched. 41 42 ### Sample Payload (for all contexts) 43 44 ```javascript 45 { 46 "Prefix": "abc", 47 "Context": "all" 48 } 49 ``` 50 51 ### Sample Request 52 53 ```shell-sessioncurl \ 54 --request POST \ 55 --data @payload.json \ 56 https://localhost:4646/v1/search 57 ``` 58 59 ### Sample Response 60 61 ```json 62 { 63 "Matches": { 64 "allocs": null, 65 "deployment": null, 66 "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"], 67 "jobs": ["abcde"], 68 "nodes": null, 69 "plugins": null, 70 "volumes": null 71 }, 72 "Truncations": { 73 "allocs": "false", 74 "deployment": "false", 75 "evals": "false", 76 "jobs": "false", 77 "nodes": "false", 78 "plugins": "false", 79 "volumes": "false" 80 } 81 } 82 ``` 83 84 #### Field Reference 85 86 - `Matches` - A map of contexts to matching arrays of identifiers. 87 88 - `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`. 89 90 ### Sample Payload (for a specific context) 91 92 ```javascript 93 { 94 "Prefix": "abc", 95 "Context": "evals" 96 } 97 ``` 98 99 ### Sample Request 100 101 ```shell-sessioncurl \ 102 --request POST \ 103 --data @payload.json \ 104 https://localhost:4646/v1/search 105 ``` 106 107 ### Sample Response 108 109 ```json 110 { 111 "Matches": { 112 "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"] 113 }, 114 "Truncations": { 115 "evals": "false" 116 } 117 } 118 ```