121 lines
2.9 KiB
Plaintext
121 lines
2.9 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Search - HTTP API
|
|
sidebar_title: Search
|
|
description: The /search endpoint is used to search for Nomad objects
|
|
---
|
|
|
|
# Search HTTP API
|
|
|
|
The `/search` endpoint returns matches for a given prefix and context, where a
|
|
context can be jobs, allocations, evaluations, nodes, deployments, plugins,
|
|
or volumes. When using Nomad Enterprise, the allowed contexts include quotas
|
|
and namespaces. Additionally, a prefix can be searched for within every context.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `POST` | `/v1/search` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | -------------------------------- |
|
|
| `NO` | `node:read, namespace:read-jobs` |
|
|
|
|
When ACLs are enabled, requests must have a token valid for `node:read` or
|
|
`namespace:read-jobs` roles. If the token is only valid for `node:read`, then
|
|
job related results will not be returned. If the token is only valid for
|
|
`namespace:read-jobs`, then node results will not be returned.
|
|
|
|
### Parameters
|
|
|
|
- `Prefix` `(string: <required>)` - Specifies the identifier against which
|
|
matches will be found. For example, if the given prefix were "a", potential
|
|
matches might be "abcd", or "aabb".
|
|
- `Context` `(string: <required>)` - Defines the scope in which a search for a
|
|
prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes",
|
|
"deployment", "plugins", "volumes" or "all", where "all" means every
|
|
context will be searched.
|
|
|
|
### Sample Payload (for all contexts)
|
|
|
|
```javascript
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": "all"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Matches": {
|
|
"allocs": null,
|
|
"deployment": null,
|
|
"evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
|
|
"jobs": ["abcde"],
|
|
"nodes": null,
|
|
"plugins": null,
|
|
"volumes": null
|
|
},
|
|
"Truncations": {
|
|
"allocs": "false",
|
|
"deployment": "false",
|
|
"evals": "false",
|
|
"jobs": "false",
|
|
"nodes": "false",
|
|
"plugins": "false",
|
|
"volumes": "false"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Field Reference
|
|
|
|
- `Matches` - A map of contexts to matching arrays of identifiers.
|
|
|
|
- `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`.
|
|
|
|
### Sample Payload (for a specific context)
|
|
|
|
```javascript
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": "evals"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Matches": {
|
|
"evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
|
|
},
|
|
"Truncations": {
|
|
"evals": "false"
|
|
}
|
|
}
|
|
```
|