diff --git a/website/source/api/search.html.md b/website/source/api/search.html.md new file mode 100644 index 000000000..ea52785d5 --- /dev/null +++ b/website/source/api/search.html.md @@ -0,0 +1,109 @@ +--- +layout: api +page_title: Search - HTTP API +sidebar_current: api-search +description: |- + The /search endpoint returns matches for a given prefix and context +--- + +# 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. +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` | `none` | + +### Parameters + +- `Prefix` `(string: )` - 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: )` - Defines the scope in which a search for a + prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes", + "deployment" or "all", meaning every context will be searched for that + identifier. + +### Sample Payload (for a specific context) + +```javascript +{ + "Prefix": "abc", + "Context": "evals" +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @payload.json \ + https://nomad.rocks/v1/search +``` + +### Sample Response + +```json +{ "Matches": { + "evals": [ + "abc2fdc0-e1fd-2536-67d8-43af8ca798ac" + ] + }, + "Truncations": { + "evals": "false" + } +} +``` + +### Sample Payload (for all contexts) + +```javascript +{ + "Prefix": "abc", + "Context": "all" +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @payload.json \ + https://nomad.rocks/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" + } +} +``` diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index cf0f9fbdd..94f2e91e2 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -51,6 +51,10 @@ Regions + > + Search + + > Status