github.com/smintz/nomad@v0.8.3/website/source/api/namespaces.html.md (about) 1 --- 2 layout: api 3 page_title: Namespace - HTTP API 4 sidebar_current: api-namespaces 5 description: |- 6 The /namespace endpoints are used to query for and interact with namespaces. 7 --- 8 9 # Namespace HTTP API 10 11 The `/namespace` endpoints are used to query for and interact with namespaces. 12 13 ~> **Enterprise Only!** This API endpoint and functionality only exists in 14 Nomad Enterprise. This is not present in the open source version of Nomad. 15 16 ## List Namespaces 17 18 This endpoint lists all namespaces. 19 20 | Method | Path | Produces | 21 | ------ | ----------------- | ------------------ | 22 | `GET` | `/v1/namespaces` | `application/json` | 23 24 The table below shows this endpoint's support for 25 [blocking queries](/api/index.html#blocking-queries) and 26 [required ACLs](/api/index.html#acls). 27 28 | Blocking Queries | ACL Required | 29 | ---------------- | ------------- | 30 | `YES` | `namespace:*`<br>Any capability on the namespace authorizes the endpoint | 31 32 ### Parameters 33 34 - `prefix` `(string: "")`- Specifies a string to filter namespaces on based on 35 an index prefix. This is specified as a querystring parameter. 36 37 ### Sample Request 38 39 ```text 40 $ curl \ 41 https://localhost:4646/v1/namespaces 42 ``` 43 44 ```text 45 $ curl \ 46 https://localhost:4646/v1/namespaces?prefix=prod 47 ``` 48 49 ### Sample Response 50 51 ```json 52 [ 53 { 54 "CreateIndex": 31, 55 "Description": "Production API Servers", 56 "ModifyIndex": 31, 57 "Name": "api-prod" 58 }, 59 { 60 "CreateIndex": 5, 61 "Description": "Default shared namespace", 62 "ModifyIndex": 5, 63 "Name": "default" 64 } 65 ] 66 ``` 67 68 ## Read Namespace 69 70 This endpoint reads information about a specific namespace. 71 72 | Method | Path | Produces | 73 | ------ | --------------------------- | -------------------------- | 74 | `GET` | `/v1/namespace/:namespace` | `application/json` | 75 76 The table below shows this endpoint's support for 77 [blocking queries](/api/index.html#blocking-queries) and 78 [required ACLs](/api/index.html#acls). 79 80 | Blocking Queries | ACL Required | 81 | ---------------- | -------------------- | 82 | `YES` | `namespace:*`<br>Any capability on the namespace authorizes the endpoint | 83 84 ### Parameters 85 86 - `:namespace` `(string: <required>)`- Specifies the namespace to query. 87 88 ### Sample Request 89 90 ```text 91 $ curl \ 92 https://localhost:4646/v1/namespace/api-prod 93 ``` 94 95 ### Sample Response 96 97 ```json 98 { 99 "CreateIndex": 31, 100 "Description": "Production API Servers", 101 "Hash": "N8WvePwqkp6J354eLJMKyhvsFdPELAos0VuBfMoVKoU=", 102 "ModifyIndex": 31, 103 "Name": "api-prod" 104 } 105 ``` 106 107 ## Create or Update Namespace 108 109 This endpoint is used to create or update a namespace. 110 111 | Method | Path | Produces | 112 | ------- | ----------------------------------------------- | -------------------------- | 113 | `POST` | `/v1/namespace/:namespace` <br> `/v1/namespace` | `application/json` | 114 115 The table below shows this endpoint's support for 116 [blocking queries](/api/index.html#blocking-queries) and 117 [required ACLs](/api/index.html#acls). 118 119 | Blocking Queries | ACL Required | 120 | ---------------- | ------------ | 121 | `NO` | `management` | 122 123 ### Parameters 124 125 - `Namespace` `(string: <required>)`- Specifies the namespace to create or 126 update. 127 128 - `Description` `(string: "")` - Specifies an optional human-readable 129 description of the namespace. 130 131 ### Sample Payload 132 133 ```javascript 134 { 135 "Namespace": "api-prod", 136 "Description": "Production API Servers" 137 } 138 ``` 139 140 ### Sample Request 141 142 ```text 143 $ curl \ 144 --request POST \ 145 --data @namespace.json \ 146 https://localhost:4646/v1/namespace/api-prod 147 ``` 148 149 ```text 150 $ curl \ 151 --request POST \ 152 --data @namespace.json \ 153 https://localhost:4646/v1/namespace 154 ``` 155 156 ## Delete Namespace 157 158 This endpoint is used to delete a namespace. 159 160 | Method | Path | Produces | 161 | ------- | -------------------------- | -------------------------- | 162 | `DELETE` | `/v1/namespace/:namespace` | `application/json` | 163 164 The table below shows this endpoint's support for 165 [blocking queries](/api/index.html#blocking-queries) and 166 [required ACLs](/api/index.html#acls). 167 168 | Blocking Queries | ACL Required | 169 | ---------------- | ------------ | 170 | `NO` | `management` | 171 172 ### Parameters 173 174 - `:namespace` `(string: <required>)`- Specifies the namespace to delete. 175 176 ### Sample Request 177 178 ```text 179 $ curl \ 180 --request DELETE \ 181 https://localhost:4646/v1/namespace/api-prod 182 ```