CloudPDF
DocsPricing
Start building

Set page measurement scale

PUT/v1/docs/{docId}/layers/{layerName}/pages/{pageKey}/scalev3.0.0-next.15

Upsert or remove EmbedPDF calibration while preserving foreign viewports. Existing annotation scales are unchanged.

Authentication#

Any one of these credentials is accepted.

API token

The deployment's static root credential (CLOUDPDF_API_AUTH_TOKENS), valid on every surface.

Document token

Doc-scoped JWT, valid only on the /v1/docs/{docId} subtree it names, gated by the capability scopes it carries (each operation's x-required-capability).

Document capabilitydoc.annotate.modify

Parameters#

docIdpathstringrequired
layerNamepathstringrequired
pageKeypathstringrequired
X-Document-Passwordheaderstring

Base64-encoded password for an encrypted document. Valid only with the API token (403 anywhere else). An encrypted document answers 422 DocPasswordRequired when the header is absent. Viewer doc JWTs use the SDK password-session flow instead.

Idempotency-Keyheaderstring

Names the change: 1 to 255 printable ASCII characters. A retry under the same key on the same layer answers with what the first request committed, and changes nothing.

Request body#

application/jsonDocPagesSetScaleRequestrequired
measureobjectrequired
subtype"rectilinear"required
ratiostring
xobject[]required
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
yobject[]
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
distanceobject[]required
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
areaobject[]required
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
angleobject[]
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
slopeobject[]
unitstringrequired
conversionnumberrequired
fraction"decimal" | "fraction" | "round" | "truncate"
precisioninteger
fixedboolean
thousandsstring
decimalstring
prefixSpacingstring
suffixSpacingstring
labelPosition"suffix" | "prefix"
originobject
xnumberrequired
ynumberrequired
cyxnumber

A complete body with every required field. Strings stand in for your own values.

{
  "measure": {
    "subtype": "rectilinear",
    "x": [
      {
        "unit": "unit",
        "conversion": 1
      }
    ],
    "distance": [
      {
        "unit": "unit",
        "conversion": 1
      }
    ],
    "area": [
      {
        "unit": "unit",
        "conversion": 1
      }
    ]
  }
}

SDK examples#

The selected SDK is remembered across the API reference. Values are examples; replace them with identifiers and input from your application.

import { CloudPDFClient } from "@cloudpdf/sdk";

const client = new CloudPDFClient({
  baseUrl: "https://yourhost.com/path/to/api",
  token: "<token>",
});

await client.doc.pages.setScale({
  docId: "docId",
  layerName: "layerName",
  pageKey: "pageKey"
});

Responses#

200OK
application/jsonDocPagesSetScale200Response
pagePageRef
kind"objectNumber"
objectNumberinteger
metaMutationMeta
affectedPagesPageRef[]
kind"objectNumber"
objectNumberinteger
cacheDeltaCacheDelta
opIdstring
undoableboolean
400Bad request
application/jsonDocPagesSetScale400Response
404Not found
application/jsonDocPagesSetScale404Response
defaultError
application/jsonEngineErrorPayload
name"EngineError"
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "SharePasswordRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "StaleBase" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused"
messagestring
detailsobjectoptional