---
title: "Update Calibration"
method: PATCH
path: "/api/v1/pages/{page_id}/calibration"
tags: ["pages"]
---

# Update Calibration

`PATCH /api/v1/pages/{page_id}/calibration`

Set or update a page's calibration; recompute affected measurements.

Atomic: writes scale_ratio + calibration columns and recomputes every
linear/area measurement on the page in a single transaction. Returns
the updated page detail and the count of recomputed measurements.

`accepted_suggestion` marks the write as an accepted detector read, the
only thing that tells it apart from hand calibration; it is rejected 422
`page_calibration_reduced_print_needs_confirmation` on a reduced print
unless `confirm_reduced_print` overrides (RUD-482, ADR-0152).

Per docs/superpowers/specs/2026-05-07-calibration-design.md §4.1, §4.3.

## Path parameters

- `page_id` string, uuid, required

## Request body

- UpdatePageCalibrationRequest — Set or update a page's calibration. Server computes scale_ratio from the embedded CalibrationData and writes both columns atomically alongside a recompute of every linear/area measurement on the page.
  - `revision_set_id` string, uuid, nullable, required
  - `calibration` CalibrationDataInput, required — User-entered calibration tuple, the shape stored in pages.calibration JSONB.
    - `drawing_distance` union, required
      - number
      - string
    - `drawing_units` 'in' | 'ft' | 'mm' | 'cm' | 'm', required
    - `actual_distance` union, required
      - number
      - string
    - `actual_units` 'in' | 'ft' | 'mm' | 'cm' | 'm', required
    - `source` 'standard' | 'manual' | 'calibrate', required
    - `description` string, required
  - `accepted_suggestion` boolean
  - `confirm_reduced_print` boolean

## Response `200`

Successful Response

- UpdatePageCalibrationResponse
  - `page` PageDetail, required — Page + derived fields for the editor. `current_extraction_id` is `None` if the page hasn't been parsed yet; `text_element_count` is the number of text elements produced by that current extraction (zero if unparsed).
    - `id` string, uuid, required
    - `drawing_id` string, uuid, required
    - `page_number` integer, required
    - `sheet_number` string, nullable
    - `sheet_title` string, nullable
    - `width` string, required
    - `height` string, required
    - `view_x0` number, nullable, required
    - `view_y0` number, nullable, required
    - `view_x1` number, nullable, required
    - `view_y1` number, nullable, required
    - `user_unit` number, required
    - `rotate` integer, required
    - `scale` string, nullable
    - `scale_ratio` string, nullable
    - `calibration` CalibrationDataOutput — User-entered calibration tuple, the shape stored in pages.calibration JSONB.
      - `drawing_distance` string, required
      - `drawing_units` 'in' | 'ft' | 'mm' | 'cm' | 'm', required
      - `actual_distance` string, required
      - `actual_units` 'in' | 'ft' | 'mm' | 'cm' | 'm', required
      - `source` 'standard' | 'manual' | 'calibrate', required
      - `description` string, required
    - `scale_source` 'autoset' | 'user' | 'import', nullable
    - `synthetic` boolean
    - `scale_suggestion` PageScaleSuggestion — What the autoset detector read off this sheet, and how much we trust it. Present whenever the current `page_scale_results` row carries exactly one distinct real (non-NTS, ratio-bearing) candidate. Absent when the sheet states no scale AND when it states several — presenting one of several as "the sheet's scale" would be worse than showing nothing (RUD-315). `ratio` is ADR-0024 canonical form (real inches per PDF point). `measured_ratio` is populated only for `contradicted`, and carries whichever evidence disagreed with the notation: the mean implied ratio of the persisted witnesses when geometry contradicted it (ADR-0144), or the VLM's independently read notation when the two readers disagreed (RUD-353). Geometry takes precedence — a witness-backed contradiction always reports the witnesses.
      - `state` 'verified' | 'contradicted' | 'unverified', required
      - `notation` string, required
      - `ratio` string, required
      - `measured_ratio` string, nullable
    - `scale_read_count` integer
    - `has_takeoff` boolean, required
    - `has_note` boolean, required
    - `markup_count` integer, required
    - `open_markup_count` integer, required
    - `current_extraction_id` string, uuid, nullable
    - `sheet_number_source` 'vlm' | 'user', nullable
    - `sheet_title_source` 'vlm' | 'user', nullable
    - `text_element_count` integer
  - `recomputed_measurement_count` integer, required

## Other responses

- `4XX` — Client Error
- `5XX` — Server Error

---

[API](https://skmtc.dev/rudus/apis/rudus-api.md) · [All operations](https://skmtc.dev/rudus/apis/rudus-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rudus/rudus-api/revisions/f149124a4d80/schema)