canonical: https://jentic.com/apis/hashicorp.com/nomad

# Hashicorp Nomad

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.

## For AI agents

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

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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 your Jentic One instance 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.

Example prompt: 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

| 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 |

## Key resources

- **Jobs** — Submit and manage job specifications
- **Allocations** — Per-task placements running on a node
- **Deployments** — Rollout progress for a job version
- **ACL Tokens** — Capability tokens used as X-Nomad-Token
- **ACL Policies** — Policy documents granting capabilities to tokens
- **Evaluations** — Scheduling evaluations triggered by job changes

## Why Jentic

- **Setup:** Wiring Nomad by hand means pointing at your own cluster's scheme, address, and port, minting an ACL token, and sending it as the X-Nomad-Token header on every call. Through Jentic you install once, import Nomad from the API Directory, store the ACL token once, and your agent calls it.
- **Permission scoping:** Nomad puts resource ids in the URL path (/allocation/{allocID}/stop, /deployment/{deploymentID}), so a rule can pin your agent to one allocation or deployment and let it read status and health for that resource. You choose the operations it may call, so destructive ones like stopping an allocation or failing a deployment are not included unless you add them.
- **Credential handling:** Your Nomad ACL token is stored once, encrypted, by your own Jentic One instance and injected as the X-Nomad-Token header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit a nomad job' or 'stop an allocation', and Jentic returns the matching Nomad operation with its input schema so the agent calls the right endpoint without reading the Nomad HTTP API documentation.

## Related APIs

- **Kubernetes** — Container orchestration with a richer ecosystem and operator pattern for teams that want full Kubernetes.
- **Docker Engine** — Container runtime that Nomad drivers invoke to run task containers on each node.
- **GitHub** — Source of truth for Nomad job specs and the GitHub Actions runners that submit jobs in GitOps flows.

## FAQ

### 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.

### Can I limit what my agent is allowed to do with the Nomad API?

Yes. Jentic One is self-hosted, so your own rules decide which Nomad operations the agent may call and which ACL token it uses. Because Nomad puts resource ids in the URL path, like /allocation/{allocID}/stop and /deployment/{deploymentID}, you can pin the agent to a single allocation or deployment and let it read status and health for that resource only. Destructive operations such as stopping an allocation or failing a deployment stay excluded unless you explicitly grant them.