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