> ## Documentation Index > Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update the fields of a model > Update the fields of a model. **Schema and spec consistency.** This endpoint does not enforce consistency between the model `schema` (the list of columns) and the model `spec` (which assigns each column a role such as `inputs`, `outputs`, `targets`, `decisions`, `metadata`, or `custom_features`). If you add a column to `schema` without also adding it to the appropriate `spec` array, the column will be ingested into the raw events table but will not appear anywhere else in the Fiddler UI. **PATCH replaces nested objects wholesale.** When you PATCH the `spec` (or `schema`) field, the request body replaces the entire nested object — any role array you omit (`inputs`, `outputs`, `targets`, `decisions`, `metadata`, `custom_features`) is reset to empty on the server. Always read the current model first and merge your additions into the existing arrays before sending the PATCH. To add columns safely, follow the multi-step sequence shown in the code samples on the right: 1. `GET /v3/models/{model_id}` — retrieve the current `schema` and `spec`. 2. `PATCH /v3/models/{model_id}` with an updated `schema` containing the existing columns plus the new columns. 3. `PATCH /v3/models/{model_id}` with an updated `spec` that preserves every existing role array and adds the new columns to the appropriate one. The Fiddler Python SDK and the Fiddler UI enforce this consistency automatically; this note applies to direct REST API integrations. ## OpenAPI ````yaml PATCH /v3/models/{model_id} openapi: 3.0.3 info: title: Fiddler API - 2.0 description: APIs to interact with Fiddler termsOfService: https://fiddler.ai/about/terms contact: email: support@fiddler.ai license: name: Proprietary url: '2.0' version: '2.0' servers: [] security: - BearerAuth: [] tags: - name: access-key description: CRUD operations for API keys - name: span-v3 - name: aggregation-invalidation-request-v3 description: Endpoints related to retrieving aggregation invalidation requests - name: alert-rules-v3 description: CRUD for Alert Rules, Summary, and Stats APIs - name: application-v3 - name: attribute-v3 - name: auth description: Authentication strategies and login flows - name: baseline-v3 description: CRUD for baseline - name: catalog-v3 description: >- Entity catalog provides paginated, searchable discovery of entity names (attribute keys, agent names, span types, span names) and their distinct values. Powered by ClickHouse materialized views — no worker or PostgreSQL dependency. - name: chart-annotation-v3 description: Endpoints related to retrieving chart annotations - name: chart-v3 description: CRUD for chart - name: queries-v3 description: v3 queries API - name: configuration-v3 description: CRUD for configurations - name: custom-metrics-v3 - name: dimensionality-reduction-v3 - name: environment-v3 description: Endpoints related to environment management - name: evals - name: datasets - name: evaluation-v3 - name: evaluator-v3 - name: rule-evaluators-v3 - name: experiment-v3 - name: explainability-v3 - name: llm_rca-v3 - name: file-upload description: Endpoints related to file uploading. - name: fql-expressions-v3 description: > Endpoints for listing FQL (Fiddler Query Language) functions available for GenAI custom metrics. Used by the frontend for autocomplete and signature hints in the FQL editor. - name: genai-alert-rules-v3 description: CRUD API for GenAI Alert Rules - name: genai-custom-metrics-v3 description: API for GenAI Custom Metrics - name: genai-metrics-v3 description: >- Endpoints for pre-aggregated GenAI metrics. All metric data is pre-aggregated by an hourly ClickHouse refreshable materialized view; no real-time aggregation is performed at request time. - name: guardrails-api description: Endpoints related to retrieving Guardrails specific data - name: ingestion-v3 - name: intercom-api description: Endpoints related to intercom APIs - name: jobs-v3 - name: llm-gateway-v3 - name: auth-login - name: auth-logout - name: metrics-v3 description: Metrics endpoints - name: model-v3 - name: dashboard-v3 - name: model-deployment-v3 - name: monitoring-summary-v3 - name: histograms-v3 - name: organization-roles-v3 description: Update user org role - name: organization-settings-v3 description: Update organization settings such as timezone, email configuration, etc. - name: pagerduty-api description: CRUD for Pagerduty services. - name: project-v3 - name: project-roles-v3 description: Project role assignment management - name: searchable-text-key-v3 description: >- Manage the global searchable text keys table that controls which OTel attribute keys are routed to the full-text-searchable `ValueContent` column in the unified attributes table. Changes propagate to the backing ClickHouse dictionary within 1-2 minutes and affect all tenants. - name: segments-v3 - name: semantic-mapping-v3 description: >- Manage the global semantic name mappings table that maps raw OTel attribute keys to canonical semantic concepts. Changes propagate to the backing ClickHouse dictionary within 1-2 minutes and affect all tenants. - name: server-info-v3 description: Endpoints related to retrieving server information - name: sessions-v3 description: v3 session APIs - name: team-roles-v3 - name: team-v3 - name: traces-v3 description: v3 trace api for monitoring - name: fetch-sessions-v3 description: v3 fetch sessions api for monitoring - name: user-access-key description: > CRUD operations for user API keys. All endpoints are user-scoped — each user can only operate on their own API keys. No one including Org admins have access to other users' API keys. - name: users-v3 - name: version-compatibility-v3 - name: webhooks externalDocs: url: https://docs.fiddler.ai description: Find out more about Fiddler paths: /v3/models/{model_id}: patch: tags: - model-v3 summary: Update the fields of a model description: | Update the fields of a model. **Schema and spec consistency.** This endpoint does not enforce consistency between the model `schema` (the list of columns) and the model `spec` (which assigns each column a role such as `inputs`, `outputs`, `targets`, `decisions`, `metadata`, or `custom_features`). If you add a column to `schema` without also adding it to the appropriate `spec` array, the column will be ingested into the raw events table but will not appear anywhere else in the Fiddler UI. **PATCH replaces nested objects wholesale.** When you PATCH the `spec` (or `schema`) field, the request body replaces the entire nested object — any role array you omit (`inputs`, `outputs`, `targets`, `decisions`, `metadata`, `custom_features`) is reset to empty on the server. Always read the current model first and merge your additions into the existing arrays before sending the PATCH. To add columns safely, follow the multi-step sequence shown in the code samples on the right: 1. `GET /v3/models/{model_id}` — retrieve the current `schema` and `spec`. 2. `PATCH /v3/models/{model_id}` with an updated `schema` containing the existing columns plus the new columns. 3. `PATCH /v3/models/{model_id}` with an updated `spec` that preserves every existing role array and adds the new columns to the appropriate one. The Fiddler Python SDK and the Fiddler UI enforce this consistency automatically; this note applies to direct REST API integrations. operationId: updateModelV3 parameters: - $ref: '#/components/parameters/model_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateModelRequest' responses: '200': description: Updated model JSON response content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/ModelDetailResponse' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' x-codeSamples: - lang: shell label: curl — schema + spec update source: | # Requires `jq`. PATCH replaces nested objects wholesale, so each # step reads the current value first and merges before sending. # 1. Retrieve the current model. current=$(curl -sS "$FIDDLER_URL/v3/models/$MODEL_ID" \ -H "Authorization: Bearer $FIDDLER_TOKEN") # 2. PATCH the schema with existing columns + new column. new_schema=$(echo "$current" | jq '.data.schema | .columns += [{"name": "new_feature", "data_type": "float"}]') curl -sS -X PATCH "$FIDDLER_URL/v3/models/$MODEL_ID" \ -H "Authorization: Bearer $FIDDLER_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --argjson s "$new_schema" '{schema: $s}')" # 3. PATCH the spec with the existing roles preserved and the # new column appended to `inputs`. Without this step the new # column will not appear in the UI beyond the raw events # table; without preserving the other arrays, existing # outputs / targets / decisions / metadata / custom_features # would be wiped. new_spec=$(echo "$current" | jq '.data.spec | .inputs += ["new_feature"]') curl -sS -X PATCH "$FIDDLER_URL/v3/models/$MODEL_ID" \ -H "Authorization: Bearer $FIDDLER_TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --argjson s "$new_spec" '{spec: $s}')" - lang: python label: Python (requests) — schema + spec update source: > import os import requests base_url = os.environ["FIDDLER_URL"].rstrip("/") model_id = os.environ["MODEL_ID"] headers = { "Authorization": f"Bearer {os.environ['FIDDLER_TOKEN']}", "Content-Type": "application/json", } url = f"{base_url}/v3/models/{model_id}" # 1. Retrieve the current model so you have the existing schema and spec. resp = requests.get(url, headers=headers) resp.raise_for_status() current = resp.json()["data"] # 2. PATCH the schema with the existing columns preserved and # the new column appended. Read-then-merge mirrors the spec # PATCH below: any top-level schema field you omit (e.g. # schema_version) is reset to its server-side default. new_schema = dict(current.get("schema") or {}) new_schema["columns"] = list(new_schema.get("columns") or []) + [ {"name": "new_feature", "data_type": "float"}, ] requests.patch( url, headers=headers, json={"schema": new_schema}, ).raise_for_status() # 3. PATCH the spec with the existing roles preserved and the # new column appended to `inputs`. Without this step the new # column will not appear in the UI beyond the raw events # table; without preserving the other arrays, existing # outputs / targets / decisions / metadata / custom_features # would be wiped. new_spec = dict(current.get("spec") or {}) new_spec["inputs"] = list(new_spec.get("inputs") or []) + ["new_feature"] requests.patch( url, headers=headers, json={"spec": new_spec}, ).raise_for_status() components: parameters: model_id: name: model_id in: path description: model id path parameter required: true schema: type: string format: uuid schemas: UpdateModelRequest: type: object properties: status: type: string enum: - LIVE - DRAFT default: LIVE version: type: string minLength: 1 maxLength: 64 default: v1 description: Version of the model input_type: $ref: '#/components/schemas/ModelInputTypeEnum' task: $ref: '#/components/schemas/ModelTaskEnum' schema: $ref: '#/components/schemas/ModelSchemaObjectRequest' spec: $ref: '#/components/schemas/ModelSpecObject' task_params: $ref: '#/components/schemas/ModelTaskParams' xai_params: $ref: '#/components/schemas/XaiParams' description: type: string nullable: true description: Description of the model owner_id: type: string nullable: true description: User ID for the owner of the model deployment_date: type: string format: date-time nullable: true description: Date the model was deployed on algorithm: type: string nullable: true description: Model algorithm framework: type: string description: >- A string providing information about the software library and version used to train and run this model nullable: true event_id_col: type: string nullable: true description: Event id column to be found in published data for the model event_ts_col: type: string nullable: true description: Timestamp column to be found in published data for the model event_ts_format: type: string nullable: true description: Format of the timestamp like datetime, epoch time etc. ApiResponse: type: object description: | Response object for standard API responses. properties: api_version: type: string default: '3.0' enum: - '2.0' - '3.0' description: | API version. kind: type: string default: NORMAL enum: - NORMAL description: | Type of response, indicating a normal response. ModelDetailResponse: required: - id - name - input_type - task - organization - project - created_at - updated_at - status allOf: - $ref: '#/components/schemas/ModelObject' - type: object properties: task_params: $ref: '#/components/schemas/ModelTaskParams' schema: $ref: '#/components/schemas/ModelSchemaObjectResponse' spec: $ref: '#/components/schemas/ModelSpecObject' event_id_col: type: string description: Event id column to be found in published data for the model event_ts_col: type: string description: Timestamp column to be found in published data for the model event_ts_format: type: string description: Format of the timestamp like datetime, epoch time etc. xai_params: $ref: '#/components/schemas/XaiParams' artifact_files: $ref: '#/components/schemas/ModelFilesObject' is_binary_ranking_model: type: boolean ModelInputTypeEnum: type: string description: | Enumeration of different model input types. enum: - text - structured ModelTaskEnum: type: string description: | Enumeration of different types of model tasks. enum: - binary_classification - multiclass_classification - regression - ranking - not_set - llm ModelSchemaObjectRequest: type: object description: Model schema with the details of each column properties: schema_version: type: integer description: Schema version default: 1 columns: type: array items: allOf: - $ref: '#/components/schemas/ModelSchemaColumnObject' - type: object properties: id: type: string description: Internal column identifier ModelSpecObject: type: object properties: schema_version: type: integer description: Schema version. Internally used. Leave empty. default: 1 inputs: type: array description: List of input columns items: type: string outputs: type: array description: List of output columns items: type: string targets: type: array description: List of target columns items: type: string decisions: type: array description: List of decision columns items: type: string metadata: type: array description: List of metadata columns items: type: string custom_features: type: array description: List of custom feature columns items: $ref: '#/components/schemas/CustomFeature' ModelTaskParams: type: object properties: binary_classification_threshold: type: number description: Threshold for labels. target_class_order: type: array description: >- If target is categorical, used to map the categories to a scale of relevance items: anyOf: - type: string - type: number - type: boolean group_by: type: string description: Query/session id column for ranking models. top_k: type: integer description: Top k results to consider when computing ranking metrics. class_weights: type: array description: Weight of each class. items: type: number weighted_ref_histograms: description: >- Whether baseline histograms must be weighted or not when calculating drift metrics. type: boolean XaiParams: type: object description: XAI parameters set for a model properties: custom_explain_methods: type: array description: >- User-defined explain_custom method of the model object defined in package.py items: type: string default_explain_method: type: string description: Default explanation method ModelObject: type: object description: Model fields JSON required: - id - name - input_type - task - organization - project - algorithm - framework - deleted_at - created_at - updated_at - created_by - version - artifact_status - status allOf: - type: object properties: id: type: string format: uuid description: UUID format unique identifier for model name: type: string description: Name of the model version: type: string description: Version of the model default: v1 status: type: string enum: - LIVE - DRAFT organization: $ref: '#/components/schemas/OrganizationCompact' project: $ref: '#/components/schemas/ProjectCompact' input_type: $ref: '#/components/schemas/ModelInputTypeEnum' task: $ref: '#/components/schemas/ModelTaskEnum' description: type: string nullable: true owner: $ref: '#/components/schemas/UserCompact' deployment_date: type: string format: date-time nullable: true description: Date the model was deployed on artifact_status: $ref: '#/components/schemas/ModelArtifactStatusEnum' deleted_at: type: string format: date-time nullable: true description: flag used internally to support soft delete of model algorithm: type: string nullable: true description: Model algorithm framework: type: string description: >- A string providing information about the software library and version used to train and run this model nullable: true created_by: $ref: '#/components/schemas/UserCompact' updated_by: $ref: '#/components/schemas/UserCompact' - $ref: '#/components/schemas/CreateUpdateTimestamp' ModelSchemaObjectResponse: type: object description: Model schema with the details of each column properties: schema_version: type: integer description: Schema version default: 1 columns: type: array items: $ref: '#/components/schemas/ModelSchemaColumnObjectResponse' ModelFilesObject: type: array items: $ref: '#/components/schemas/ModelArtifactsResponse' ErrorResponse: type: object description: | Response object for errors returned by the API. properties: api_version: type: string default: '3.0' enum: - '2.0' - '3.0' description: | API version of the response. kind: type: string default: ERROR enum: - ERROR description: | Type of response, usually indicating an error. error: type: object properties: code: type: integer format: int32 description: > Represents the code for this error, typically an HTTP response code. default: 400 enum: - 400 - 403 - 404 - 500 message: type: string description: > A human-readable message providing more details about the error. If there are multiple errors, it will be the message for the first error. example: Resource Not Found errors: type: array description: > Container for additional information regarding the error, especially for multiple errors. items: type: object properties: reason: type: string description: > Unique identifier for this error, different from the error code. example: ResourceNotFoundException message: type: string description: > A human-readable message providing more details about the error. If there is only one error, this field will match error.message. example: Resource Not Found help: type: string description: > Link to support or documentation providing more information on the error. ModelSchemaColumnObject: type: object description: A model column representation required: - name - data_type properties: name: type: string description: Column name data_type: $ref: '#/components/schemas/ModelColumnsDataTypeEnum' min: type: number description: Min value of integer/float column max: type: number description: Max value of integer/float column categories: type: array description: List of unique values of a categorical column items: anyOf: - type: string - type: number - type: boolean bins: type: array description: >- Bin boundary values for integer/float column histograms. Must be a strictly increasing array of numbers spanning [min, max]. If omitted, uniform bins are auto-generated from min and max. Minimum 2 and maximum 16 boundary values (1 to 15 bins). items: type: number maxItems: 16 minItems: 2 replace_with_nulls: type: array description: Replace the list of given values to null if found in the events data items: anyOf: - type: string - type: number n_dimensions: type: integer description: Number of dimensions of a vector column CustomFeature: type: object required: - name properties: type: type: string enum: - FROM_COLUMNS - FROM_VECTOR - FROM_TEXT_EMBEDDING - FROM_IMAGE_EMBEDDING - ENRICHMENT name: description: Name of the custom feature type: string columns: type: array items: type: string centroids: type: array items: type: number tf_idf: type: array items: type: object n_clusters: type: integer monitor_components: type: boolean OrganizationCompact: type: object title: OrganizationCompact description: > Compact version of an organization which can be included in the response of relevant APIs. required: - id - name properties: id: type: string format: uuid description: | Unique identifier of the organization. name: type: string description: | Name of the organization. ProjectCompact: type: object title: ProjectCompact description: > Compact version of a project which can be included in the response of relevant APIs. required: - id - name properties: id: type: string format: uuid description: | Unique identifier of the project. name: type: string description: | Name of the project. asset_type: type: string enum: - ML_MODEL - GEN_AI_APP description: | Type of assets the project can have. UserCompact: type: object title: UserCompactV3 description: > Compact version of a user which can be included in the response of relevant APIs. required: - id - email properties: id: type: string format: uuid readOnly: true description: | Unique identifier for the user. full_name: type: string readOnly: true description: | Full name of the user. email: type: string format: email description: | Email address of the user. ModelArtifactStatusEnum: type: string description: | Enumeration of different model artifact statuses. enum: - no_model - surrogate - user_uploaded CreateUpdateTimestamp: type: object required: - created_at - updated_at properties: created_at: type: string format: date-time readOnly: true description: | Date and time when the object was created. updated_at: type: string format: date-time readOnly: true description: | Date and time when the object was last updated. ModelSchemaColumnObjectResponse: allOf: - $ref: '#/components/schemas/ModelSchemaColumnObject' - type: object properties: id: type: string description: Internal column identifier required: - id ModelArtifactsResponse: type: object required: - name - size - modified properties: name: type: string size: type: integer modified: type: string format: date-time ModelColumnsDataTypeEnum: type: string description: Data type of the column enum: - int - float - str - bool - category - timestamp - vector responses: '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer ````