---
title: "Replace document (full replacement)"
method: PUT
path: "/api/v1/documents/{identifier}"
tags: ["Documents"]
deprecated: true
---

# Replace document (full replacement)

`PUT /api/v1/documents/{identifier}`

> **Deprecated.**

**Deprecated** — use `PATCH /api/v2/documents/{identifier}/draft` (and the related `/draft` routes). Removed on July 31, 2026: this endpoint now returns `410` unless your organization has been granted a migration extension. Contact support if you need one.

Updates a document with the specified identifier. This endpoint performs a full resource replacement — all required fields must be provided and existing query presentations are replaced entirely. Only dashboard documents are supported; analysis documents and documents without an associated dashboard return 400. For published documents, the update goes through a draft/publish workflow automatically; if a draft already exists, the request returns 409 unless `clearExistingDraft` is set to `true`.

## Path parameters

- `identifier` string, required — Document identifier (either document ID or identifier slug)

## Request body

- DocumentsPutBody
  - `clearExistingDraft` boolean — Clear existing draft before updating (for published documents with drafts)
  - `description` string, nullable — Document description
  - `documentMetadata` unknown
  - `facetFilters` boolean, required — Enable facet filters
  - `filterConfig` unknown
  - `filterOrder` string[], required — Order of filters
  - `modelId` string, required — Model ID
  - `name` string, required — Document name
  - `queryPresentations` DocumentsPutQueryPresentation[], required — Query presentations (full replacement)
    - `aiConfig` object — AI configuration
      - `description` object
        - `aiContext` string
        - `enabled` boolean
      - `subTitle` object
        - `aiContext` string
        - `enabled` boolean
    - `chartType` 'auto' | 'area' | 'areaStacked' | 'areaStackedPercentage' | 'bar' | 'barLine' | 'barGrouped' | 'barStacked' | 'barStackedPercentage' | 'boxplot' | 'code' | 'column' | 'columnGrouped' | 'columnStacked' | 'columnStackedPercentage' | 'heatmap' | 'kpi' | 'line' | 'lineColor' | 'map' | 'regionMap' | 'markdown' | 'omni-ai-summary-markdown' | 'pie' | 'funnel' | 'sankey' | 'point' | 'pointColor' | 'pointSize' | 'pointSizeColor' | 'singleRecord' | 'omni-spreadsheet' | 'summaryValue' | 'svgMap' | 'table' | 'treemap' | 'null', nullable — Chart type
    - `description` string — Description
    - `name` string, required — Query presentation name
    - `prefersChart` boolean — Whether to prefer chart view
    - `query` unknown
    - `queryIdentifierMapKey` string — Round-trip preservation hint. When the value matches an existing key on the document, the tile keeps its map key (and dashboard containers stay attached). Omit for new tiles. Must be a positive integer string (e.g. "1", "2", "10").
    - `resultConfig` unknown
    - `subTitle` string — Subtitle
    - `topicName` string, nullable — Topic name. Omit or pass null for raw-SQL tiles or any tile with no semantic topic.
    - `visConfig` ApiVisConfig, nullable — Visualization configuration
      - `config` object — Visualization spec (chart configuration)
      - `fields` string[], nullable — Field names used in the visualization
      - `visType` 'vegalite' | 'omni-ai-summary-markdown' | 'basic' | 'omni-kpi' | 'map' | 'omni-markdown' | 'funnel' | 'sankey' | 'single-record' | 'svg-map' | 'treemap' | 'omni-spreadsheet' | 'spreadsheet-tab' | 'summary-value' | 'omni-table' — Visualization type (e.g. basic, omni-markdown, omni-table)
  - `refreshInterval` integer, nullable, required — Auto-refresh interval in seconds

## Response `200`

Document replaced successfully

- DocumentsPutResponse
  - `description` string, nullable — Document description
  - `identifier` string, required — Document identifier
  - `name` string, required — Updated document name

## Other responses

- `400` — Invalid request body, missing required fields, or validation error (also returned for analysis documents and documents without an associated dashboard)
- `401` — Authentication required
- `403` — Insufficient permissions to update the document
- `404` — Document not found
- `409` — Draft already exists - set clearExistingDraft to true to discard it and proceed
- `410` — Endpoint has been removed; the organization does not hold a migration extension

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/4701f292c621/schema)