» 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 and required 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)

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

» Sample Payload (for all contexts)

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

» Sample Request

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

» Sample Response

{ "Matches": {
    "allocs": [],
    "deployment": [],
    "evals": [
      "abc2fdc0-e1fd-2536-67d8-43af8ca798ac"
    ],
    "jobs": [
      "abcde"
    ],
    "nodes": []
  },
  "Truncations": {
    "allocs": "false",
    "deployment": "false",
    "evals": "false",
    "jobs": "false",
    "nodes": "false"
  }
}