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.

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"
  }
}