---
title: "Drop an index from a ledger"
method: DELETE
path: "/v3/{ledgerName}/indexes/{canonicalId}"
tags: ["Indexes"]
---

# Drop an index from a ledger

`DELETE /v3/{ledgerName}/indexes/{canonicalId}`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/{ledgerName}/indexes/{canonicalId}`
- Auth: one of:
  - HTTP bearer
  - none

Removes an index from a ledger. The path parameter carries the target
`IndexID` in canonical form (e.g. `metadata:TARGET_TYPE_ACCOUNT:color`,
`tx_builtin:TX_BUILTIN_INDEX_TIMESTAMP`). Requires `ledger:WriteLedger` scope.

The drop is idempotent. An `IndexID` that has no registry entry on the
ledger (never created, or already dropped) also answers `204`, and each
committed drop appends a `DROP_INDEX` entry to the ledger log. A
mistyped canonical id is therefore not reported; read the index with
`GET /v3/{ledgerName}/indexes/{canonicalId}` first when the caller must
know that it exists. `404` means that the ledger does not exist.

## Path parameters

- `ledgerName` string, required
- `canonicalId` string, required

## Headers

- `Idempotency-Key` string

## Response `204`

Index removed, or no index with this id was registered on the ledger.

## Other responses

- `400`: Bad request
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `404`: The ledger does not exist. A missing index does not produce `404`.
- `409`: Conflict (e.g. idempotency key conflict, ledger deleted)
- `429`: Resource exhausted. Write admission can reject with `WRITES_BLOCKED_DISK_FULL` while disk pressure blocks writes; `SEQUENCE_EXHAUSTED` means an authoritative identifier allocator cannot allocate another identifier and is permanent for that allocator. Inspect `errorCode` before deciding whether to retry. No retry interval is supplied, and retrying cannot resolve sequence exhaustion.
- `500`: Internal server error
- `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`).

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `dropIndex` removed and replaced with `v3DropIndex`
- **2026-10-08** `3da23d327316`: 3 info
  - added the media type `text/plain` for the response with the status `401`
  - added the media type `text/plain` for the response with the status `403`
  - added the non-success response with the status `429`
- **2026-09-30** `b747efd5cd77`: 1 info
  - endpoint added
- **2026-09-29** `6ff73ac9a6bd`: 1 breaking
  - api path removed without deprecation
- **2026-09-10** `2f4f658e3f4a`: 1 info
  - added the non-success response with the status `503`

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/indexes/:canonicalId/delete.md)

---

[API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)