---
title: "Apply an index change (create or drop)"
method: POST
path: "/instances/{id}/index-changes"
tags: ["Query Insights"]
---

# Apply an index change (create or drop)

`POST /instances/{id}/index-changes`

## Request

- Base URL: `https://api.cloudpepper.io`
- URL: `https://api.cloudpepper.io/instances/{id}/index-changes`
- Auth: HTTP bearer

Guardrailed per-index DROP / CREATE on the instance's managed PostgreSQL database — the apply half of index-health. Not a SQL runner: inputs are bare identifiers and a fixed non-unique btree shape, every executed statement is assembled from the database's own quote_ident() tokens, and a refuse-ladder rejects any integrity index (primary/unique/exclusion/constraint-backed/replica-identity/extension-owned/partitioned) and any used index (idx_scan > 0) before execution.

**drop_index** runs synchronously (DROP INDEX CONCURRENTLY) and returns `status: applied`.

**create_index** is validated synchronously and the online build (CREATE INDEX CONCURRENTLY) is handed to a background worker — the endpoint returns HTTP 202 `status: accepted`. Poll the resolve endpoint (type=index, name=<returned index.name>) until it reports `valid: true`. btree-only; UNIQUE is not supported in v1.

**Key Parameters:**
- `id`: The instance whose database to change
- `action`: `create_index` or `drop_index`

## Request body

- object
  - `action` 'create_index' | 'drop_index', required
  - `table` string: create_index only — the table to index (bare identifier, schema public)
  - `columns` string[]: create_index only — 1 to 8 distinct columns (bare identifiers)
  - `method` 'btree': create_index only — btree is the only supported method in v1
  - `index_name` string: drop_index only — the index to drop (bare identifier, schema public)

## Response `200`

drop_index applied (DROP INDEX CONCURRENTLY completed)

- object

## Other responses

- `202`: create_index accepted — the online build runs in the background; poll the resolve endpoint (type=index) until `valid: true`
- `400`: Invalid request (body `status`: invalid, with a machine-readable `reason`, e.g. invalid_action / invalid_table_name / invalid_columns / unsupported_method)
- `404`: Instance, table, column, or index not found (body `status`: not_found, with `reason`)
- `409`: Refused by the safety ladder or unavailable (body `status`: refused | unavailable, with `reason`, e.g. index_is_unique / index_in_use / index_too_large / postgres_version_too_old / external_database_not_supported)

---

[API](https://skmtc.dev/cloudpepper/apis/cloudpepper-api-docs.md) · [All operations](https://skmtc.dev/cloudpepper/apis/cloudpepper-api-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudpepper/apis/cloudpepper-api-docs/revisions/b6a59274cedc?raw)