github.com/smintz/nomad@v0.8.3/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  ```