Endpoints for querying and managing client nodes registered with the Nomad cluster.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nomad:nomad-nodes-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: HashiCorp Nomad HTTP Nodes API
description: The HashiCorp Nomad HTTP API provides programmatic access to all Nomad functionality including job scheduling, allocation management, node operations, deployments, services, evaluations, namespaces, ACL policies, and cluster status. All API routes are prefixed with /v1/ and the default port is 4646. The API is RESTful, responds to standard HTTP verbs, and supports ACL token authentication via the X-Nomad-Token header or Bearer scheme.
version: 1.9.0
contact:
name: HashiCorp Support
url: https://support.hashicorp.com
termsOfService: https://www.hashicorp.com/terms-of-service
license:
name: Business Source License 1.1
url: https://github.com/hashicorp/nomad/blob/main/LICENSE
servers:
- url: http://localhost:4646/v1
description: Local Nomad Agent
security:
- nomadToken: []
- bearerAuth: []
tags:
- name: Nodes
description: Endpoints for querying and managing client nodes registered with the Nomad cluster.
paths:
/nodes:
get:
operationId: listNodes
summary: List nodes
description: Lists all client nodes registered with Nomad. Supports prefix-based filtering on node ID.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/PrefixParam'
- $ref: '#/components/parameters/NextTokenParam'
- $ref: '#/components/parameters/PerPageParam'
- $ref: '#/components/parameters/FilterParam'
responses:
'200':
description: A list of node stubs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NodeListStub'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/node/{nodeID}:
get:
operationId: readNode
summary: Read a node
description: Returns the full details of the specified node.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/NodeIDParam'
responses:
'200':
description: Node details
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/node/{nodeID}/evaluate:
put:
operationId: evaluateNode
summary: Create a new evaluation for a node
description: Creates a new evaluation for the specified node. This can be used to force a re-evaluation of the node and its allocations.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/NodeIDParam'
responses:
'200':
description: Evaluation created
content:
application/json:
schema:
type: object
properties:
EvalIDs:
type: array
items:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/node/{nodeID}/drain:
post:
operationId: drainNode
summary: Set node drain mode
description: Enables or disables drain mode on the specified node. When draining is enabled, no further allocations will be assigned to this node, and existing allocations will be migrated.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/NodeIDParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
DrainSpec:
type: object
properties:
Deadline:
type: integer
description: Deadline in nanoseconds for the drain to complete.
IgnoreSystemJobs:
type: boolean
description: If true, system jobs are not drained from the node.
MarkEligible:
type: boolean
description: If true, marks the node as eligible for scheduling.
responses:
'200':
description: Node drain updated
content:
application/json:
schema:
type: object
properties:
EvalIDs:
type: array
items:
type: string
NodeModifyIndex:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/node/{nodeID}/purge:
delete:
operationId: purgeNode
summary: Purge a node
description: Purges a node from the system. The node must be in a down state.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/NodeIDParam'
responses:
'200':
description: Node purged
content:
application/json:
schema:
type: object
properties:
EvalIDs:
type: array
items:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
NodeIDParam:
name: nodeID
in: path
required: true
description: The ID of the node.
schema:
type: string
PrefixParam:
name: prefix
in: query
description: Specifies a string to filter results based on an ID prefix.
schema:
type: string
PerPageParam:
name: per_page
in: query
description: Maximum number of results to return per page.
schema:
type: integer
NextTokenParam:
name: next_token
in: query
description: Indicates where to start paging for queries that support pagination.
schema:
type: string
FilterParam:
name: filter
in: query
description: Specifies the expression used to filter the results.
schema:
type: string
schemas:
Node:
type: object
description: A Nomad client node.
properties:
ID:
type: string
description: The unique ID of the node.
Datacenter:
type: string
Name:
type: string
NodeClass:
type: string
NodePool:
type: string
Drain:
type: boolean
description: Whether the node is in drain mode.
SchedulingEligibility:
type: string
description: Whether the node is eligible for scheduling.
enum:
- eligible
- ineligible
Status:
type: string
description: The status of the node.
enum:
- initializing
- ready
- down
- disconnected
StatusDescription:
type: string
Drivers:
type: object
additionalProperties:
type: object
properties:
Detected:
type: boolean
Healthy:
type: boolean
HealthDescription:
type: string
Attributes:
type: object
additionalProperties:
type: string
Resources:
$ref: '#/components/schemas/Resources'
Reserved:
$ref: '#/components/schemas/Resources'
HTTPAddr:
type: string
TLSEnabled:
type: boolean
CreateIndex:
type: integer
ModifyIndex:
type: integer
Resources:
type: object
description: Resource requirements for a task.
properties:
CPU:
type: integer
description: CPU required in MHz.
Cores:
type: integer
description: Number of CPU cores required.
MemoryMB:
type: integer
description: Memory required in MB.
MemoryMaxMB:
type: integer
description: Maximum memory in MB (memory oversubscription).
DiskMB:
type: integer
description: Disk space required in MB.
Networks:
type: array
items:
$ref: '#/components/schemas/NetworkResource'
NodeListStub:
type: object
description: A stub representation of a node returned in list operations.
properties:
ID:
type: string
Datacenter:
type: string
Name:
type: string
NodeClass:
type: string
NodePool:
type: string
Drain:
type: boolean
SchedulingEligibility:
type: string
Status:
type: string
StatusDescription:
type: string
Version:
type: string
Drivers:
type: object
additionalProperties:
type: object
CreateIndex:
type: integer
ModifyIndex:
type: integer
NetworkResource:
type: object
description: Network resource configuration.
properties:
Mode:
type: string
description: The network mode (bridge, host, cni).
Device:
type: string
CIDR:
type: string
IP:
type: string
MBits:
type: integer
DNS:
type: object
properties:
Servers:
type: array
items:
type: string
DynamicPorts:
type: array
items:
type: object
properties:
Label:
type: string
Value:
type: integer
To:
type: integer
HostNetwork:
type: string
ReservedPorts:
type: array
items:
type: object
properties:
Label:
type: string
Value:
type: integer
To:
type: integer
HostNetwork:
type: string
responses:
InternalError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
message:
type: string
Unauthorized:
description: Unauthorized - missing or invalid ACL token
content:
application/json:
schema:
type: object
properties:
message:
type: string
NotFound:
description: Resource not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
securitySchemes:
nomadToken:
type: apiKey
name: X-Nomad-Token
in: header
description: ACL token passed via the X-Nomad-Token request header.
bearerAuth:
type: http
scheme: bearer
description: ACL token passed via the Authorization header with Bearer scheme.
externalDocs:
description: Nomad HTTP API Documentation
url: https://developer.hashicorp.com/nomad/api-docs