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