nomad/website/source/api/namespaces.html.md

layout, page_title, sidebar_current, description

layout	page_title	sidebar_current	description
api	Namespace - HTTP API	api-namespaces	The /namespace endpoints are used to query for and interact with namespaces.

Namespace HTTP API

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

~> Enterprise Only! This API endpoint and functionality only exists in Nomad Enterprise. This is not present in the open source version of Nomad.

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 querystring 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"
    },
    {
        "CreateIndex": 5,
        "Description": "Default shared namespace",
        "ModifyIndex": 5,
        "Name": "default"
    }
]

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

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

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

Sample Payload

{
  "Namespace": "api-prod",
  "Description": "Production API Servers"
}

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