Hashicorp Nomad

Name: Nomad API
Brand: Nomad
Availability: InStock

✓ Official Vendor SpecCloud InfrastructureContainer OrchestrationapiKey99 EndpointsREST

For Agents

Submit Nomad jobs, inspect deployments and allocations, and manage ACL tokens and policies on a Nomad cluster.

Install Jentic One Beta

Connect the Nomad to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Nomad, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with Nomad API.

Submit a new job specification or update an existing job on a Nomad cluster

List allocations for a job and stop a specific allocation by ID

Inspect a deployment's progress and post allocation health updates

Bootstrap and manage ACL policies and tokens for cluster authorization

GET STARTED

Start building with Nomad API

Explore with Jentic

View OpenAPI Document

Nomad is HashiCorp's workload orchestrator that schedules containers, binaries, and Java applications across a cluster of agents. The HTTP API exposes 99 endpoints for submitting and managing jobs, deployments, allocations, evaluations, ACL policies and tokens, and cluster resources like Sentinel policies and quotas. Authentication is an X-Nomad-Token header carrying a Nomad ACL token; tokens have policies attached that determine which endpoints they can call. The API runs against the Nomad agent's HTTP listener (default port 4646) and is the same surface used by the Nomad CLI.

Use Cases

Patterns agents use Nomad API for, with concrete tasks.

★ GitOps Job Deployment

Wire a CI pipeline that submits a Nomad job spec on every merge to main by calling POST against the jobs endpoint and polling the matching deployment. The API returns evaluation IDs that the pipeline tracks until the deployment reports successful, with allocation health posted via POST /deployment/allocation-health/{deploymentID}. This replaces ad-hoc nomad job run shell calls with a structured API flow.

Submit the contents of api-server.nomad as a job to the cluster, poll the matching deployment, and confirm all allocations report healthy.

Cluster ACL Bootstrap and Token Rotation

Bootstrap a fresh Nomad cluster's ACL system with POST /acl/bootstrap, then create policies via POST /acl/policy/{policyName} and tokens via POST /acl/token/{tokenAccessor}. Tokens can be rotated by deleting the old accessor with DELETE /acl/token/{tokenAccessor} and minting a new one. This API surface replaces manual nomad acl CLI commands for repeatable cluster setup.

Bootstrap ACLs on the cluster with POST /acl/bootstrap, then create a 'deploy' policy and a token tied to it for the CI service.

Allocation Triage and Recovery

Build an SRE triage tool that inspects failing allocations via GET /allocation/{allocID} and stops them with POST /allocation/{allocID}/stop, kicking off a fresh placement. Combined with GET /deployment/allocations/{deploymentID}, the tool can surface unhealthy allocations and route a rollback through POST /deployment/fail/{deploymentID}. Useful during an incident when a bad image is rolling out.

List allocations for deployment 'dep-789' via GET /deployment/allocations/dep-789, stop any in 'failed' status, and call POST /deployment/fail/dep-789 if more than half are unhealthy.

AI Agent Cluster Operator

Let an SRE copilot answer 'what's running on the cluster' and 'why is service X down' by chaining /allocations, /deployment/{id}, and /allocation/{allocID}/services through Jentic. The X-Nomad-Token sits in the Jentic vault and is injected on each call, so an operator's token never leaks into agent transcripts. Destructive endpoints can be gated with human approval policies.

When asked 'why is api-server failing', list allocations for the api-server job, fetch the latest failed allocation, and return its events and exit code.

Key Endpoints

99 endpoints — nomad is hashicorp's workload orchestrator that schedules containers, binaries, and java applications across a cluster of agents.

METHOD

PATH

DESCRIPTION

POST

/acl/bootstrap

Bootstrap ACLs on a fresh cluster

GET

/acl/tokens

List all ACL tokens

POST

/acl/token/{tokenAccessor}

Create or update an ACL token

GET

/allocations

List allocations across the cluster

POST

/allocation/{allocID}/stop

Stop an allocation

GET

/deployment/{deploymentID}

Get deployment status

POST

/deployment/fail/{deploymentID}

Mark a deployment failed

POST

/deployment/allocation-health/{deploymentID}

Post allocation health for a deployment

POST

/acl/bootstrap

Bootstrap ACLs on a fresh cluster

GET

/acl/tokens

List all ACL tokens

POST

/acl/token/{tokenAccessor}

Create or update an ACL token

GET

/allocations

List allocations across the cluster

POST

/allocation/{allocID}/stop

Stop an allocation

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Nomad ACL tokens are stored encrypted in the Jentic vault and injected as the X-Nomad-Token header per call. Operator and CI tokens stay out of agent prompts and tool transcripts.

Intent-based discovery

Agents search Jentic for 'submit a nomad job' or 'stop an allocation' and Jentic returns the matching endpoint with its schema, removing the need to read the Nomad HTTP API documentation.

Time to first call

Direct integration: 2-5 days to model jobs, deployments, allocations, ACLs, and blocking queries. Through Jentic: under an hour for single-operation workflows.

FAQs

Specific to using Nomad API through Jentic.

What authentication does the Nomad API use?

Nomad uses ACL tokens passed as the X-Nomad-Token header. Tokens are bootstrapped via POST /acl/bootstrap and have ACL policies attached that determine which endpoints they can call. Through Jentic the token is held in the encrypted vault and injected per call, so it never enters the agent's prompt context.

Can I submit a Nomad job through the API?

Yes. The Nomad HTTP API exposes job submission and management endpoints; the OpenAPI spec covers the v1 surface used by the Nomad CLI. Once submitted, the API returns an evaluation ID that you poll until the deployment is complete.

What are the rate limits for the Nomad API?

Nomad does not impose a fixed per-second HTTP rate limit; throughput is bound by the Nomad servers' capacity and any reverse proxy in front of them. Long-running blocking queries (using ?wait=) and high-frequency polling can starve other clients, so use blocking queries with index parameters where possible.

How do I list ACL tokens through Jentic?

Search Jentic for 'list nomad acl tokens', load the schema for GET /acl/tokens, and execute against your cluster's address. Run pip install jentic and use the async client.search, client.load, and client.execute pattern. The X-Nomad-Token header is supplied automatically from the vault.

Does the Nomad API include Consul or Vault operations?

No. This OpenAPI spec covers Nomad only. Consul service discovery and Vault secret retrieval happen through Nomad's integrations at runtime but are not part of the Nomad HTTP API surface — use the Consul or Vault APIs directly for those operations.

Where is the Nomad API hosted — is there a public endpoint?

Nomad is self-hosted: the API runs on each Nomad agent's HTTP listener (default port 4646) on your own infrastructure. The base URL in this spec uses scheme, address, and port template variables so the same spec works for any cluster you operate.

Hashicorp Nomad

Connect the Nomad to your agent

Capabilities

Start building with Nomad API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs