open-nomad/website/source/api/search.html.md

layout	page_title	sidebar_current	description
api	Search - HTTP API	api-search	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 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"
  }
}