--- layout: api page_title: Admin Partition - HTTP API description: The /partition endpoints allow for managing Consul Enterprise Admin Partitions. --- # Admin Partition - HTTP API The functionality described here is available only in [Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.11.0 and later. ## Create a Partition This endpoint creates a new Partition. | Method | Path | Produces | | ------ | ------------ | ------------------ | | `PUT` | `/partition` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | The corresponding CLI command is [`consul partition create`](/commands/partition#create). ### Parameters - `Name` `(string: )` - The partition name. This must be a valid DNS hostname label. - `Description` `(string: "")` - Free form partition description. ### Sample Payload ```json { "Name": "na-west", "Description": "Partition for North America West" } ``` ### Sample Request ```shell-session $ curl ---request PUT \ --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ --data @payload.json \ http://127.0.0.1:8500/v1/partition ``` ### SampleResponse ```json { "Name": "na-west", "Description": "Partition for North America West", "CreateIndex": 55, "ModifyIndex": 55 } ``` ## Read a Partition This endpoint reads a Partition with the given name. | Method | Path | Produces | | ------ | ------------------ | ------------------ | | `GET` | `/partition/:name` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------- | | `NO` | `consistent` | `none` | `operator:read` or `none`1 | 1 A non-anonymous token can read its own partition. The corresponding CLI command is [`consul partition read`](/commands/partition#read). ### Parameters - `name` `(string: )` - Specifies the partition to read. This is required and is specified as part of the URL path. ### Sample Request ```shell-session $ curl --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \ http://127.0.0.1:8500/v1/partition/na-west ``` ### SampleResponse ```json { "Name": "na-west", "Description": "Partition for North America West", "CreateIndex": 55, "ModifyIndex": 55 } ``` ## Update a Partition This endpoint updates a Partition description. | Method | Path | Produces | | ------ | ------------------ | ------------------ | | `PUT` | `/partition/:name` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | The corresponding CLI command is [`consul partition write`](/commands/partition#write). ### Parameters - `Name` `(string: )` - The partition name. This must be a valid DNS hostname label. If present in the payload it must match what was given in the URL path. - `Description` `(string: "")` - Free form partition description. ### Sample Payload ```json { "Description": "North America West Partition" } ``` ### Sample Request ```shell-session $ curl --request PUT \ --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ --data @payload.json \ http://127.0.0.1:8500/v1/partition/na-west ``` ### SampleResponse ```json { "Name": "na-west", "Description": "North America West Partition", "CreateIndex": 55, "ModifyIndex": 60 } ``` ## Delete a Partition This endpoint marks a Partition for deletion. Once marked Consul will deleted all the associated partitioned data in the background. Only once all associated data has been deleted will the Partition actually disappear. Until then, further reads can be performed on the partition and a `DeletedAt` field will now be populated with the timestamp of when the Partition was marked for deletion. | Method | Path | Produces | | -------- | ------------------ | -------- | | `DELETE` | `/partition/:name` | N/A | This endpoint will return no data. Success or failure is indicated by the status code returned. The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | The corresponding CLI command is [`consul partition delete`](/commands/partition#delete). ### Parameters - `name` `(string: )` - Specifies the partition to delete. This is required and is specified as part of the URL path. ### Sample Request ```shell-session $ curl --request DELETE \ --header "X-Consul-Token: b23b3cad-5ea1-4413-919e-c76884b9ad60" \ http://127.0.0.1:8500/v1/partition/na-west ``` ### Sample Read Output After Deletion Prior to Removal ```json { "Name": "na-west", "Description": "North America West Partition", "DeletedAt": "2021-12-14T23:00:00Z", "CreateIndex": 55, "ModifyIndex": 100 } ``` ## List all Partitions This endpoint lists all the Partitions. | Method | Path | Produces | | ------ | ------------- | ------------------ | | `GET` | `/partitions` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `consistent` | `none` | `operator:read` | The corresponding CLI command is [`consul partition list`](/commands/partition#list). ### Sample Request ```shell-session $ curl --header "X-Consul-Token: 0137db51-5895-4c25-b6cd-d9ed992f4a52" \ http://127.0.0.1:8500/v1/partitions ``` ### Sample Response ```json [ { "Name": "default", "Description": "Builtin Default Partition", "CreateIndex": 6, "ModifyIndex": 6 }, { "Name": "na-west", "Description": "North America West Partition", "CreateIndex": 55, "ModifyIndex": 55 } ] ```