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.

Method	Path	Produces
`GET`	`/v1/namespaces`	`application/json`

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

Blocking Queries	ACL Required
`YES`	`namespace:*` 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?prefix=prod

Sample Response

[  {    "CreateIndex": 31,    "Description": "Production API Servers",    "ModifyIndex": 31,    "Name": "api-prod",    "Quota": ""  },  {    "CreateIndex": 5,    "Description": "Default shared namespace",    "ModifyIndex": 5,    "Name": "default",    "Quota": ""  }]

Read Namespace

This endpoint reads information about a specific namespace.

Method	Path	Produces
`GET`	`/v1/namespace/:namespace`	`application/json`

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

Blocking Queries	ACL Required
`YES`	`namespace:*` 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/api-prod

Sample Response

{  "CreateIndex": 31,  "Description": "Production API Servers",  "Quota": "",  "Hash": "N8WvePwqkp6J354eLJMKyhvsFdPELAos0VuBfMoVKoU=",  "ModifyIndex": 31,  "Name": "api-prod"}

Create or Update Namespace

This endpoint is used to create or update a namespace.

Method	Path	Produces
`POST`	`/v1/namespace/:namespace` `/v1/namespace`	`application/json`

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

Blocking Queries	ACL Required
`NO`	`management`

Parameters

Name (string: <required>)- Specifies the namespace to create or update.
Description (string: "") - Specifies an optional human-readable description of the namespace.
Quota (string: "") - Specifies an quota to attach to the namespace.

Sample Payload

{  "Name": "api-prod",  "Description": "Production API Servers",  "Quota": "prod-quota"}

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

Delete Namespace

This endpoint is used to delete a namespace.

Method	Path	Produces
`DELETE`	`/v1/namespace/:namespace`	`application/json`

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

Blocking Queries	ACL Required
`NO`	`management`

Parameters

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

Sample Request

$ curl \    --request DELETE \    https://localhost:4646/v1/namespace/api-prod