fb5091678b
Should provide cut and paste example for most users. Advanced users should be able to correct URLs to something appropriate.
115 lines
2.6 KiB
Markdown
115 lines
2.6 KiB
Markdown
---
|
|
layout: api
|
|
page_title: Search - HTTP API
|
|
sidebar_current: api-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, or deployments. 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/index.html#blocking-queries) and
|
|
[required ACLs](/api/index.html#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 identifer 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" or "all", where "all" means every context will be searched.
|
|
|
|
### Sample Payload (for a specific context)
|
|
|
|
```javascript
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": "evals"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```text
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{ "Matches": {
|
|
"evals": [
|
|
"abc2fdc0-e1fd-2536-67d8-43af8ca798ac"
|
|
]
|
|
},
|
|
"Truncations": {
|
|
"evals": "false"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Payload (for all contexts)
|
|
|
|
```javascript
|
|
{
|
|
"Prefix": "abc",
|
|
"Context": ""
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```text
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/search
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{ "Matches": {
|
|
"allocs": [],
|
|
"deployment": [],
|
|
"evals": [
|
|
"abc2fdc0-e1fd-2536-67d8-43af8ca798ac"
|
|
],
|
|
"jobs": [
|
|
"abcde"
|
|
],
|
|
"nodes": []
|
|
},
|
|
"Truncations": {
|
|
"allocs": "false",
|
|
"deployment": "false",
|
|
"evals": "false",
|
|
"jobs": "false",
|
|
"nodes": "false"
|
|
}
|
|
}
|
|
```
|