---
title: "Create a Metadata Index"
method: POST
path: "/v1/settings/metadata-indexes/entities/{entity_name}"
tags: ["Metadata Indexes API"]
---

# Create a Metadata Index

`POST /v1/settings/metadata-indexes/entities/{entity_name}`

Use this endpoint to create a metadata index for a specific entity type. Metadata indexes improve query performance when filtering or searching by custom metadata fields.

## Path parameters

- `entity_name` 'organization' | 'ledger' | 'asset' | 'segment' | 'portfolio' | 'account' | 'transaction' | 'operation' | 'account_type' | 'operation_route' | 'transaction_route', required

## Headers

- `Content-Type` string
- `X-Request-Id` string, uuid
- `Authorization` string

## Request body

- CreateMetadataIndexRequest — The request body to create a metadata index.
  - `metadataKey` string, required — The metadata key to be indexed. This key must match the metadata field name used in your entities.
  - `unique` boolean — Indicates whether the index enforces uniqueness. When set to `true`, duplicate values for this metadata key will not be allowed.
  - `sparse` boolean — Indicates whether the index is sparse. When set to `true`, only documents containing the indexed field will be included in the index.

## Response `201`

Indicates that the metadata index was successfully created and the operation was completed as expected.

- MetadataIndexResponse — The response body for a metadata index.
  - `indexName` string, required — The name of the index in the database.
  - `entityName` string, required — The name of the entity associated with the index.
  - `metadataKey` string, required — The metadata key used in the index.
  - `unique` boolean, required — Indicates whether the index enforces uniqueness.
  - `sparse` boolean, required — Indicates whether the index is sparse (ignores documents without the indexed field).

## Other responses

- `400`
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict — a metadata index with the same key already exists for this entity type.
- `500` — Internal Server Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)