github.com/uchennaokeke444/nomad@v0.11.8/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-session
    54  $ curl \
    55      --request POST \
    56      --data @payload.json \
    57      https://localhost:4646/v1/search
    58  ```
    59  
    60  ### Sample Response
    61  
    62  ```json
    63  {
    64    "Matches": {
    65      "allocs": null,
    66      "deployment": null,
    67      "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
    68      "jobs": ["abcde"],
    69      "nodes": null,
    70      "plugins": null,
    71      "volumes": null
    72    },
    73    "Truncations": {
    74      "allocs": "false",
    75      "deployment": "false",
    76      "evals": "false",
    77      "jobs": "false",
    78      "nodes": "false",
    79      "plugins": "false",
    80      "volumes": "false"
    81    }
    82  }
    83  ```
    84  
    85  #### Field Reference
    86  
    87  - `Matches` - A map of contexts to matching arrays of identifiers.
    88  
    89  - `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`.
    90  
    91  ### Sample Payload (for a specific context)
    92  
    93  ```javascript
    94  {
    95    "Prefix": "abc",
    96    "Context": "evals"
    97  }
    98  ```
    99  
   100  ### Sample Request
   101  
   102  ```shell-session
   103  $ curl \
   104      --request POST \
   105      --data @payload.json \
   106      https://localhost:4646/v1/search
   107  ```
   108  
   109  ### Sample Response
   110  
   111  ```json
   112  {
   113    "Matches": {
   114      "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
   115    },
   116    "Truncations": {
   117      "evals": "false"
   118    }
   119  }
   120  ```