Reorder form widgets

POST/v1/docs/{docId}/layers/{layerName}/form/widgets/{pageKey}/reorderv3.0.0-next.15

Change the stacking order of one page's widgets: they go together, in the order given, next to a neighbour widget or to the bottom (`'start'`) or top (`'end'`) of the page's widgets, which paint above every annotation. Where the page's `/Tabs` follows it, this is also the tab order. Returns the page's new widget order.

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.forms.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/jsonDocFormsReorderWidgetsRequestrequired

widgetsAnnotationRef[]required

kind =

kind"objectNumber"required

pagePageRefrequired

kind"objectNumber"required

objectNumberintegerrequired

positionAnnotationPositionrequired

one of

A complete body for each shape. Strings stand in for your own values.

{
  "widgets": {
    "kind": "objectNumber",
    "page": {
      "kind": "objectNumber",
      "objectNumber": 1
    },
    "objectNumber": 1
  },
  "position": "start"
}

SDK examples#

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

This body offers a choice, and the example takes one branch: it sends widgets as objectNumber. The request body above carries the other shape — baseIndex.

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

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

await client.doc.forms.reorderWidgets({
  docId: "docId",
  layerName: "layerName",
  pageKey: "pageKey",
  widgets: [{
      kind: "objectNumber",
      page: {
        kind: "objectNumber",
        objectNumber: 1
      },
      objectNumber: 1
    }],
  position: "start"
});

Responses#

200OK

application/jsonDocFormsReorderWidgets200Response

pagePageRef

kind"objectNumber"

objectNumberinteger

orderAnnotationRef[]

kind =

kind"objectNumber"

pagePageRef

kind"objectNumber"

objectNumberinteger

metaFormMutationMeta

affectedPagesPageRef[]

kind"objectNumber"

objectNumberinteger

cacheDeltaCacheDelta

opIdstring

undoableboolean

changedFieldsFormFieldRef[]

kind =

kind"objectNumber"

objectNumberinteger

changedWidgetsFormWidget[]

refAnnotationRef

objectNumberinteger

pagePageRef

redrawnWidgetsFormWidget[]

refAnnotationRef

objectNumberinteger

pagePageRef

400Bad request

application/jsonDocFormsReorderWidgets400Response

404Not found

application/jsonDocFormsReorderWidgets404Response

defaultError

application/jsonEngineErrorPayload

name"EngineError"

messagestring

detailsobjectoptional