Indexes

The FastAPI Index surface manages identity and explores formulas, canonical datasets, values, relationships, and delete impact. Formula mutation remains a typed-library operation through FormulaIndex.

Routes

All operations are present in the Adapter from API contract. Create, update, delete, and the formula save, activate and retire routes are mutations; the previews are queries that persist nothing.

GET /api/v1/index/by-uids/?uid__in=<uid>&uid__in=<uid> is a bounded batch lookup (ADR 0047): uid__in is repeated or comma-separated, at most 500, the matching rows return in request order inside a ResourceCollection, unknown uids are omitted, and there is no paging, search or discovery route. include=<sidecar MetaTable uid> attaches provider sidecar rows under includes[<uid>], as described for accounts.

Identity Payload

Create requires:

{
  "unique_identifier": "USD-SWAP-10Y",
  "index_type": "interest_rate",
  "display_name": "USD 10Y Swap Rate",
  "calculation_method": "custom",
  "value_format": "percent",
  "value_suffix": null
}

calculation_method is formula or custom. value_format is decimal or percent; the optional suffix is presentation text. No provider, methodology owner, result-unit registry, or effective-date field exists on identity.

Listing

GET /api/v1/index/ supports:

search, index_type, has_formula, has_canonical_values, cadence
limit, offset

The response is command-center.resource_collection@v1; UI metadata comes from GET /api/v1/index/discovery/. has_canonical_values and cadence query indexed availability metadata; they do not scan each canonical table for distinct identifiers.

Formula Responses

Formula history returns version, status, validity, formula, policies, hash, and input count. Detail adds alignment parameters, metadata, and exact inputs:

{
  "source_reference": {
    "type": "index",
    "identifier": "MXN-TIIE-28D"
  },
  "meta_table_uid": "11111111-1111-1111-1111-111111111111",
  "observable": "price"
}

The response has no source key, resolver object, configurable identity/value columns, selectors, transforms, coefficients, or units.

Formula Lifecycle

Formula creation, lifecycle and preview go through msm.api.FormulaIndex (ADR 0037, ADR 0038); the routes are thin wrappers that take the Index identity from the stored row and record the acting identity (ADR 0047).

• POST /api/v1/index/{uid}/formulas/ with {"definition": ..., "inputs": [...]} persists one version through FormulaIndex.upsert. definition is an IndexFormulaDefinition (valid_from, formula, alignment_policy, alignment_parameters_json, missing_data_policy, optional status, version, valid_to, metadata_json); inputs are the exact source bindings shown above. A definition identical to a stored version returns that version; otherwise the next monotonic version is stored as draft unless status asks for active or retired. 400 for a formula that fails the contract or an Index with calculation_method="custom", 404 for an unknown Index or source, 409 when the row cannot be stored. Returns the IndexFormulaDetail with 201.
• POST /api/v1/index/{uid}/formulas/{definition_uid}/activate/ activates a draft and retires the open predecessor atomically.
• POST /api/v1/index/{uid}/formulas/{definition_uid}/retire/ retires a version at valid_to (body, optional; now by default).
• POST /api/v1/index/{uid}/formulas/preview/ with {"definition": ..., "inputs": [...], "start": ..., "end": ...} validates an unsaved formula, reads the pinned source MetaTables over the window through TimeIndexTableRef and returns the calculated observations as core.tabular_frame@v1 (time_index, index_identifier, value, definition_uid, observation_status, source_as_of, metadata_json; timestamps as epoch milliseconds). Nothing is persisted.
• POST /api/v1/index/{uid}/formulas/{definition_uid}/preview/ with {"start": ..., "end": ...} does the same for a stored version.

start and end must be timezone-aware and end later than start. A definition uid that belongs to another Index is 404.

Related MetaTables

Asset and Index related-table routes accept:

• numeric=true: require a numeric non-identity column;
• timestamped=true: require a registered time-indexed table.

Both default to true. False disables only that filter. Responses use the same RelatedMetaTable schema. Relationships are proven by registered FK metadata; column names alone are not accepted. Catalog discovery is paginated and does not read source values.

Dataset States

Per-Index dataset listing returns:

• populated when reconciliation found rows;
• compatible_empty when a compatible query found none;
• unavailable when access or query failure prevented a count.

Compatible-empty rows are hidden unless include_empty=true. Unavailable rows remain visible and are not represented as empty.

Bounded Values

Value requests require timezone-aware start and end, order=asc|desc, and a limit from 1 to 5,000. The selected Index identifier is always applied as a server-side dimension filter. The response is core.tabular_frame@v1.

Rows contain numeric value and optional provenance. Observation unit is not part of the response; display formatting belongs to the Index identity.

Deletion

Deletion uses the same direct row API as other core resources:

DELETE /api/v1/index/{uid}/

It returns null on success and 404 when missing. Database CASCADE, SET NULL, RESTRICT, and NO ACTION constraints govern relationships. There is no signing secret, confirmation token, or deletion executor.

GET /delete-impact/ is read-only preflight metadata. It does not change the delete operation.

Related Documentation

• Formula and custom Index tutorial
• Formula and custom Index workflow
• ADR 0038