Hashicorp Nomad
✓ 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.
Use for: Submit a new Nomad job from a job spec, Stop allocation 'alloc-1234' on the Nomad cluster, List all current ACL tokens on the cluster, Bootstrap ACLs on a fresh Nomad cluster
Not supported: Does not handle Consul service discovery, Vault secrets, or Terraform state — use for Nomad job, allocation, deployment, and ACL operations on a Nomad cluster only.
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.
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.
1
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 | sh2
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 instanceJentic 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
Exchange a one-time token for a Nomad ACL token
Query cluster resources like nodes, agents, evaluations, and Sentinel policies
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
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
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.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Complementary
GitHub
Source of truth for Nomad job specs and the GitHub Actions runners that submit jobs in GitOps flows.
Use GitHub when the agent needs to read job spec files from a repo or report deployment status back to a pull request.
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.
GET STARTED