> ## Documentation Index > Fetch the complete documentation index at: https://docs.tilt.io/llms.txt > Use this file to discover all available pages before exploring further. # Apply construction > Save and evaluate a Tilt methodology atomically. ## OpenAPI ````yaml api-reference/index-construction-preview-openapi.yaml PATCH /api/v1/tilts/{tilt_uuid} openapi: 3.1.0 info: title: 'Tilt Index Construction API: Design Preview' version: 0.4.0-design-preview summary: >- A restrained public projection of Tilt's existing index construction workflow. description: | A Tilt is a persistent project for one index methodology. Its construction rules are the source, evaluated constituent snapshots are the build artifacts, and methodology history is version history. This bounded repository analogy does not imply branches, forks, merges, or cloning. This contract covers rules-based equity construction only. Applying construction saves the rules, evaluates them, and commits the complete weighted constituent snapshot atomically. servers: - url: https://x.invalid description: Non-routable design preview security: - ApiKey: [] tags: - name: Tilts description: Organization-owned Tilt projects and versions. - name: Construction description: Apply methodology and read its saved weighted evaluation. - name: Catalog description: >- Discover fields, functions, universes, and classifications used in expressions. - name: Tickers description: Resolve security identifiers to exact Tilt asset IDs. - name: Backtests description: Backtest a saved Tilt using its configured rebalance behavior. paths: /api/v1/tilts/{tilt_uuid}: parameters: - $ref: '#/components/parameters/TiltUuid' patch: tags: - Construction summary: Apply and evaluate construction description: > Merges supplied fields into the saved construction, evaluates the resulting methodology at the current evaluation date, and atomically commits both the rules and complete weighted constituent snapshot. Omitted fields, including nested rule fields, preserve saved values. Explicit `null` clears nullable fields. Validation, evaluation, and revision-conflict failures save neither rules nor constituents. Send the `revision` returned by a prior read or apply as `base_revision` to prevent overwriting a newer edit. A request containing only `base_revision` re-evaluates the unchanged methodology. Applying to a published Tilt can create a new draft UUID; use the response's `tilt_uuid` for subsequent reads. operationId: applyTiltConstruction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TiltConstructionUpdate' example: base_revision: '2026-09-29T14:32:10Z' assignment_expression: quality = 2 * revenue_growth_3y + roe filter_expression: market_cap > 5000 and fcf_margin > 0.08 score_expression: quality weight_expression: free_float_market_cap rules: max_constituents: 20 rebalancing_period: QUARTERLY capping_methodology: THRESHOLD_BASED max_position_weight: '0.10' top_n_position_threshold: '0.045' top_n_position_weight: '0.45' responses: '200': description: The effective methodology and its evaluation were committed. content: application/json: schema: $ref: '#/components/schemas/ConstructionApplyResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: The Tilt changed after the edit began; nothing was saved. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: revision_conflict message: >- The Tilt changed after this edit started. Reload it and apply the edit again. '422': description: >- The effective construction could not be evaluated; nothing was saved. content: application/json: schema: $ref: '#/components/schemas/ConstructionError' components: parameters: TiltUuid: name: tilt_uuid in: path required: true schema: type: string format: uuid schemas: TiltConstructionUpdate: type: object additionalProperties: false minProperties: 1 properties: base_revision: type: string format: date-time description: >- Recommended optimistic-concurrency token from the latest read or apply. universe_preset: type: string minLength: 1 description: >- Omit to preserve. Valid IDs come from the universe presets endpoint; null is not accepted. size_segment_base_date: type: - string - 'null' format: date description: >- Historical anchor for size-segment eligibility, not the evaluation date. assignment_expression: type: - string - 'null' description: >- One named derived-field assignment per line. Null clears all assignments. filter_expression: type: string minLength: 1 description: Boolean eligibility expression. Use `True` for no additional filter. score_expression: type: - string - 'null' description: >- Ranking expression. Null clears ranking and requires max_constituents to be null. weight_expression: type: - string - 'null' description: >- Relative sizing expression. Null sizes by score, or equally when score is also null. included_tilt_asset_ids: type: array uniqueItems: true items: type: string minLength: 1 description: >- Complete replacement for always-included listings. An empty array clears it. excluded_tilt_asset_ids: type: array uniqueItems: true items: type: string minLength: 1 description: >- Complete replacement for always-excluded listings. An empty array clears it. rules: $ref: '#/components/schemas/ConstructionRulesUpdate' ConstructionApplyResult: type: object required: - success - tilt_uuid - version_group_sqid - revision - universe_preset - assignment_expression - filter_expression - score_expression - weight_expression - included_tickers - excluded_tickers - rules - evaluation properties: success: type: boolean const: true tilt_uuid: type: string format: uuid description: Authoritative version UUID for subsequent reads. version_group_sqid: type: string revision: type: string format: date-time universe_preset: type: string size_segment_base_date: type: - string - 'null' format: date assignment_expression: type: - string - 'null' filter_expression: type: string score_expression: type: - string - 'null' weight_expression: type: - string - 'null' included_tickers: type: array items: $ref: '#/components/schemas/TickerReference' excluded_tickers: type: array items: $ref: '#/components/schemas/TickerReference' rules: $ref: '#/components/schemas/ConstructionRules' evaluation: $ref: '#/components/schemas/EvaluationSummary' Error: type: object required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string ConstructionError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: unknown_columns: type: array items: type: string closest_matches: type: array items: type: string unresolved_tickers: type: array items: type: object additionalProperties: true ambiguous_tickers: type: array items: type: object additionalProperties: true ConstructionRulesUpdate: type: object additionalProperties: false properties: rebalancing_period: oneOf: - $ref: '#/components/schemas/RebalancePeriod' - type: 'null' description: Omit to preserve; null disables cadence. capping_methodology: $ref: '#/components/schemas/CappingMethodology' max_position_weight: $ref: '#/components/schemas/NullableRatio' top_n_positions: type: - integer - 'null' minimum: 1 top_n_position_weight: $ref: '#/components/schemas/NullableRatio' top_n_position_threshold: $ref: '#/components/schemas/NullableRatio' max_constituents: type: - integer - 'null' minimum: 1 description: Requires an effective score expression when non-null. TickerReference: type: object required: - tilt_asset_id - symbol - name - exchange properties: tilt_asset_id: type: string symbol: type: string name: type: string exchange: type: - string - 'null' ConstructionRules: type: object required: - rebalancing_period - capping_methodology - max_position_weight - top_n_positions - top_n_position_weight - top_n_position_threshold - max_constituents properties: rebalancing_period: oneOf: - $ref: '#/components/schemas/RebalancePeriod' - type: 'null' capping_methodology: $ref: '#/components/schemas/CappingMethodology' max_position_weight: $ref: '#/components/schemas/NullableRatio' top_n_positions: type: - integer - 'null' top_n_position_weight: $ref: '#/components/schemas/NullableRatio' top_n_position_threshold: $ref: '#/components/schemas/NullableRatio' max_constituents: type: - integer - 'null' minimum: 1 EvaluationSummary: type: object required: - as_of_date - total_constituents - total_weight - top_constituents properties: as_of_date: type: string format: date total_constituents: type: integer total_weight: type: number description: >- Sum of fractional constituent weights; approximately 1 for a nonempty weighted result. top_constituents: type: array description: >- A convenience preview only. Read `/constituents` for the complete saved result. items: $ref: '#/components/schemas/EvaluationPreviewConstituent' RebalancePeriod: type: string enum: - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY CappingMethodology: type: string enum: - NONE - FIXED_TOP_N - THRESHOLD_BASED NullableRatio: type: - string - 'null' pattern: ^(0(\.\d+)?|1(\.0+)?)$ description: Decimal portfolio fraction from 0 through 1, encoded as a string. EvaluationPreviewConstituent: type: object additionalProperties: false required: - ticker - score - weight properties: ticker: type: string score: type: - number - 'null' weight: type: number minimum: 0 maximum: 1 description: >- Portfolio fraction; unlike the current CLI presentation, this is not a percentage-point value. responses: BadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The Tilt was not found in the API key's organization. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKey: type: apiKey in: header name: X-Api-Key ````