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, namespaces, or volumes. When using Nomad Enterprise, the allowed contexts include quotas. Additionally, a prefix can be searched for within every context.

The table below shows this endpoint's support for blocking queries and required ACLs.

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)

{  "Prefix": "abc",  "Context": "all"}

Sample Request

$ curl \    --request POST \    --data @payload.json \    https://localhost:4646/v1/search

Sample Response

{  "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)

{  "Prefix": "abc",  "Context": "evals"}

Sample Request

$ curl \    --request POST \    --data @payload.json \    https://localhost:4646/v1/search

Sample Response

{  "Matches": {    "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]  },  "Truncations": {    "evals": "false"  }}