Index Management

MongoDB index inspection and maintenance. Each model the platform stores has an expected set of indexes (declared via Settings.indexes, Indexed() annotations, or index_helper suggestions); these endpoints let an operator audit what's currently present in MongoDB versus what's expected, clean up dead indexes, and rebuild missing ones.

Scopes

Scope	Reach
admin	All index-management endpoints.

Endpoints

List Models

GET /api/admin/indexes/models

Returns every model name the index manager knows about. The model names returned here are the values to pass as {model_name} on the other endpoints.

Required scope: admin · also accepts API key

Response 200 — list of model identifiers.

Get Index Status

GET /api/admin/indexes/{model_name}/status

Returns a comprehensive snapshot of the model's index situation, including:

• Expected indexes — declared via Settings.indexes, Indexed() annotations, or fields marked use_in_query=True.
• Actual indexes — what currently exists in MongoDB.
• Dead indexes — exist in MongoDB but no longer expected.
• Missing indexes — expected but not present.
• Coverage report — quick summary of healthy / unhealthy state.
• Suggested indexes — heuristic recommendations from index_helper.

Required scope: admin · also accepts API key

Path parameters

Name	Type	Required	Description
model_name	string	yes	Model name (see List Models).

Response 200 — IndexStatusResponse

Clean Up Dead Indexes

POST /api/admin/indexes/{model_name}/cleanup

Removes indexes that exist in MongoDB but are not expected (not declared, not annotated, not suggested). Defaults to dry-run mode — pass dry_run=false to actually remove indexes.

Required scope: admin

Path parameters

Name	Type	Required	Description
model_name	string	yes	Model name.

Query parameters

Name	Type	Default	Description
dry_run	boolean	true	When true, report what would be removed without actually doing it.

Response 200 — CleanupResponse

Recreate Missing Indexes

POST /api/admin/indexes/{model_name}/recreate

Creates any expected indexes that are currently missing from MongoDB. Does not touch existing indexes.

Required scope: admin

Path parameters

Name	Type	Required	Description
model_name	string	yes	Model name.

Response 200 — RecreateResponse

Recreate All Indexes (Drop & Recreate)

POST /api/admin/indexes/{model_name}/recreate-all

Drops every index on the model (except _id_) and recreates them all. Use this when the index set has drifted significantly or when you suspect a corrupted index — it is the heavier hammer compared to /recreate.

Required scope: admin

Path parameters

Name	Type	Required	Description
model_name	string	yes	Model name.

Response 200 — RecreateResponse

WARNING

Dropping and recreating indexes can cause temporary read-performance degradation while MongoDB rebuilds them. Run during a maintenance window for large collections.

See also

• System Defaults — recreate default records (different from indexes).
• System Health — service-level health snapshots.