github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/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  namespaces, or volumes. When using Nomad Enterprise, the allowed contexts
    13  include quotas. Additionally, a prefix can be searched for within every
    14  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-docs#blocking-queries) and
    22  [required ACLs](/api-docs#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 identifier 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", "plugins", "volumes" or "all", where "all" means every
    41    context will be searched.
    42  
    43  ### Sample Payload (for all contexts)
    44  
    45  ```javascript
    46  {
    47    "Prefix": "abc",
    48    "Context": "all"
    49  }
    50  ```
    51  
    52  ### Sample Request
    53  
    54  ```shell-session
    55  $ curl \
    56      --request POST \
    57      --data @payload.json \
    58      https://localhost:4646/v1/search
    59  ```
    60  
    61  ### Sample Response
    62  
    63  ```json
    64  {
    65    "Matches": {
    66      "allocs": null,
    67      "deployment": null,
    68      "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
    69      "jobs": ["abcde"],
    70      "nodes": null,
    71      "plugins": null,
    72      "volumes": null
    73    },
    74    "Truncations": {
    75      "allocs": "false",
    76      "deployment": "false",
    77      "evals": "false",
    78      "jobs": "false",
    79      "nodes": "false",
    80      "plugins": "false",
    81      "volumes": "false"
    82    }
    83  }
    84  ```
    85  
    86  #### Field Reference
    87  
    88  - `Matches` - A map of contexts to matching arrays of identifiers.
    89  
    90  - `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`.
    91  
    92  ### Sample Payload (for a specific context)
    93  
    94  ```javascript
    95  {
    96    "Prefix": "abc",
    97    "Context": "evals"
    98  }
    99  ```
   100  
   101  ### Sample Request
   102  
   103  ```shell-session
   104  $ curl \
   105      --request POST \
   106      --data @payload.json \
   107      https://localhost:4646/v1/search
   108  ```
   109  
   110  ### Sample Response
   111  
   112  ```json
   113  {
   114    "Matches": {
   115      "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
   116    },
   117    "Truncations": {
   118      "evals": "false"
   119    }
   120  }
   121  ```