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  ```