• Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
  • HTTP API Overview

  • Libraries & SDKs
  • JSON Jobs

  • ACL Policies
  • ACL Tokens
  • Agent
  • Allocations
  • Client
  • Deployments
  • Evaluations
  • Events
  • Jobs
  • Namespaces
  • Nodes
  • Metrics
    • Overview
    • Autopilot
    • Raft
    • License
    • Scheduler
    • Snapshot
  • Plugins
  • Quotas
  • Recommendations
  • Regions
  • Scaling Policies
  • Search
  • Sentinel Policies
  • Services
  • Status
  • System
  • UI
  • Validate
  • Volumes
Type '/' to Search

»Namespace HTTP API

The /namespace endpoints are used to query for and interact with namespaces.

Prior to Nomad 1.0 Namespaces were an Enterprise-only feature.

»List Namespaces

This endpoint lists all namespaces.

MethodPathProduces
GET/v1/namespacesapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:*
Any capability on the namespace authorizes the endpoint

»Parameters

  • prefix (string: "")- Specifies a string to filter namespaces on based on an index prefix. This is specified as a query string parameter.

»Sample Request

$ curl \
    https://localhost:4646/v1/namespaces
$ curl \
    https://localhost:4646/v1/namespaces
$ curl \
    https://localhost:4646/v1/namespaces?prefix=prod
$ curl \
    https://localhost:4646/v1/namespaces?prefix=prod

»Sample Response

[
  {
    "Capabilities": null,
    "CreateIndex": 1,
    "Description": "Default shared namespace",
    "Meta": null,
    "ModifyIndex": 1,
    "Name": "default",
    "Quota": ""
  },
  {
    "Capabilities": null,
    "CreateIndex": 17,
    "Description": "Development Staging Namespace",
    "Meta": {
        "type": "dev",
        "contact": "helpdesk@example.com"
    },
    "ModifyIndex": 17,
    "Name": "staging",
    "Quota": ""
  }
]
[
  {
    "Capabilities": null,
    "CreateIndex": 1,
    "Description": "Default shared namespace",
    "Meta": null,
    "ModifyIndex": 1,
    "Name": "default",
    "Quota": ""
  },
  {
    "Capabilities": null,
    "CreateIndex": 17,
    "Description": "Development Staging Namespace",
    "Meta": {
        "type": "dev",
        "contact": "helpdesk@example.com"
    },
    "ModifyIndex": 17,
    "Name": "staging",
    "Quota": ""
  }
]

»Read Namespace

This endpoint reads information about a specific namespace.

MethodPathProduces
GET/v1/namespace/:namespaceapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace:*
Any capability on the namespace authorizes the endpoint

»Parameters

  • :namespace (string: <required>)- Specifies the namespace to query.

»Sample Request

$ curl \
    https://localhost:4646/v1/namespace/staging
$ curl \
    https://localhost:4646/v1/namespace/staging

»Sample Response

{
  "Capabilities": null,
  "CreateIndex": 17,
  "Description": "Development Staging Namespace",
  "Meta": {
    "type": "dev",
    "contact": "helpdesk@example.com"
  },
  "ModifyIndex": 17,
  "Name": "staging",
  "Quota": ""
}
{
  "Capabilities": null,
  "CreateIndex": 17,
  "Description": "Development Staging Namespace",
  "Meta": {
    "type": "dev",
    "contact": "helpdesk@example.com"
  },
  "ModifyIndex": 17,
  "Name": "staging",
  "Quota": ""
}

»Create or Update Namespace

This endpoint is used to create or update a namespace.

MethodPathProduces
POST/v1/namespace/:namespace
/v1/namespace
application/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOmanagement

»Parameters

  • Name (string: <required>)- Specifies the namespace to create or update.

  • Description (string: "") - Specifies an optional human-readable description of the namespace.

  • Meta (object: null) - Optional object with string keys and values of metadata to attach to the namespace. Namespace metadata is not used by Nomad and is intended for use by operators and third party tools.

  • Quota (string: "") - Specifies an quota to attach to the namespace.

»Sample Payload

{
  "Name": "api-prod",
  "Description": "Production API Servers",
  "Meta": {
    "contact": "platform-eng@example.com"
  },
  "Quota": "prod-quota"
}
{
  "Name": "api-prod",
  "Description": "Production API Servers",
  "Meta": {
    "contact": "platform-eng@example.com"
  },
  "Quota": "prod-quota"
}

Note that the Quota key is Enterprise-only.

»Sample Request

$ curl \
    --request POST \
    --data @namespace.json \
    https://localhost:4646/v1/namespace/api-prod
$ curl \
    --request POST \
    --data @namespace.json \
    https://localhost:4646/v1/namespace/api-prod
$ curl \
    --request POST \
    --data @namespace.json \
    https://localhost:4646/v1/namespace
$ curl \
    --request POST \
    --data @namespace.json \
    https://localhost:4646/v1/namespace

»Delete Namespace

This endpoint is used to delete a namespace.

MethodPathProduces
DELETE/v1/namespace/:namespaceapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOmanagement

»Parameters

  • :namespace (string: <required>)- Specifies the namespace to delete.

»Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/namespace/api-prod
$ curl \
    --request DELETE \
    https://localhost:4646/v1/namespace/api-prod
github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager