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/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: <required>)` - 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 -X PUT \
   -H "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`<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).

### Parameters

- `name` `(string: <required>)` - Specifies the partition to read. This
  is required and is specified as part of the URL path.

### Sample Request

```shell-session
$ curl -H "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: <optional>)` - 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 -X PUT \
   -H "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: <required>)` - Specifies the partition to delete. This
  is required and is specified as part of the URL path.

### Sample Request

```shell-session
$ curl -X DELETE \
   -H "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 -H "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
  }
]
```