consul/website/content/api-docs/admin-partitions.mdx

---
layout: api
page_title: Admin Partition - HTTP API
description: The /partition endpoints allow for managing Consul Enterprise Admin Partitions.
---

# Admin Partition - HTTP API

<EnterpriseAlert />

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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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).

### JSON Request Body Schema

- `Name` `(string: <required>)` - The partition name. This field 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
```

### Sample Response

```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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                          |
| ---------------- | ----------------- | ------------- | ------------------------------------- |
| `NO`             | `consistent`      | `none`        | `operator:read` or `none`<sup>1</sup> |

<sup>1</sup> A non-anonymous token can read its own partition.

The corresponding CLI command is [`consul partition read`](/commands/partition#read).

### Path Parameters

- `name` `(string: <required>)` - Specifies the partition to read.

### 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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).

### Path Parameters

- `name` `(string: <required>)` - Specifies the partition to update.
  This parameter must be a valid DNS hostname label.

### JSON Request Body Schema

- `Name` `(string: <optional>)` - If specified, this field must be an exact match
  with the `name` path parameter.

- `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
```

### Sample Response

```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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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).

### Path Parameters

- `name` `(string: <required>)` - Specifies the partition to delete.

### 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-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/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
  }
]
```