Reference

Deployment

client.deployment.license_status() -> DeploymentLicenseStatusResponse

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.deployment.license_status()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc

client.doc.head(...) -> DocHead200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.head(
    doc_id="docId",
)

⚙️ Parameters

doc_id: str

document_password: typing.Optional[str] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.changes(...) -> DocChanges200Response

📝 Description

Each change stands on its own and names itself by opId: a refused change rolls back alone, and the answer lists every change in order, applied with its result or refused with its error. Asked again under its opId, a change gets the same answer, refusals included; a different change under an answered opId is refused (IdempotencyKeyReused). { opId, undoOf } undoes an earlier change of the caller, here or in an earlier request; an undo leaves alone what was changed since, and the undo of an undo redoes. A redaction, a flatten, a form repair or a completed signature ends undo for the changes before it (UndoUnavailable). Each op is checked against its own capability: annotation ops need doc.annotate.modify, form values doc.forms.fill, form structure doc.forms.modify, metadata doc.metadata.modify. Bytes (a stamp's drawing, an attached file, a signature's artwork) travel as multipart: a JSON body part, each op naming its files by role as resources: { <role>: '<key>' }, and each file as the part resource:<key>. At most 64 changes per request and 512 ops per change.

🔌 Usage

from cloudpdf import CloudPDFClient
from cloudpdf.doc import DocChangesRequestChangesItem

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.changes(
    doc_id="docId",
    layer_name="layerName",
    changes=[
        DocChangesRequestChangesItem(
            op_id="opId",
        )
    ],
)

⚙️ Parameters

doc_id: str

layer_name: str

changes: typing.List[DocChangesRequestChangesItem]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.download(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.download(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.manifest(...) -> DocManifest200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.manifest(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.render(...) -> typing.Iterator[bytes]

📝 Description

Render parameters (viewport, format) pass as flat dotted query keys, e.g. ?viewport.kind=width&viewport.width=800; the full grammar is documented with the viewer.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.render(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.text(...) -> DocText200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.text(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.exchange(...) -> SharesExchange200Response

📝 Description

Unauthenticated, but requires a browser Origin header, checked against the grant allowlist. Unknown, revoked, and disabled tokens are indistinguishable (404). Passphrase-protected grants return 422 SharePasswordRequired until password is supplied. Mounted only when the deployment can sign (HS256 mode).

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.exchange(
    share_token="shareToken",
)

⚙️ Parameters

share_token: str

password: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.list(...) -> SharesList200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.list(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

doc_id: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.create(...) -> SharesCreate200Response

📝 Description

The returned share id is the public share token. Mounted only when the deployment can sign (HS256 mode) — exchange mints session JWTs, so grants exist only where minting does.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.create(
    tenant_id="tenantId",
    doc_id="docId",
    scope=[
        "scope"
    ],
)

⚙️ Parameters

tenant_id: str

doc_id: str

scope: typing.List[str]

layer_name: typing.Optional[str]

origins: typing.Optional[typing.List[str]]

password: typing.Optional[str]

session_ttl_seconds: typing.Optional[int]

expires_at: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.get(...) -> SharesGet200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.get(
    tenant_id="tenantId",
    share_id="shareId",
)

⚙️ Parameters

tenant_id: str

share_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.delete(...)

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.delete(
    tenant_id="tenantId",
    share_id="shareId",
)

⚙️ Parameters

tenant_id: str

share_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.shares.update(...) -> SharesUpdate200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.shares.update(
    tenant_id="tenantId",
    share_id="shareId",
)

⚙️ Parameters

tenant_id: str

share_id: str

scope: typing.Optional[typing.List[str]]

origins: typing.Optional[typing.List[str]]

password: typing.Optional[str]

session_ttl_seconds: typing.Optional[int]

disabled: typing.Optional[bool]

expires_at: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Tenants

client.tenants.list(...) -> TenantsList200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.list()

⚙️ Parameters

limit: typing.Optional[int]

cursor: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.create(...) -> TenantsCreate200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.create(
    id="id",
)

⚙️ Parameters

id: str

name: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.get(...) -> TenantsGet200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.get(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.delete(...)

📝 Description

Destroys the tenant and everything in its namespace — documents, layers, stored bytes, audit history. Irreversible.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.delete(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.resume(...)

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.resume(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.suspend(...)

📝 Description

Instantly reversible with resume. The API token is exempt, so a suspended tenant can still be inspected, exported, resumed, or deleted.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.suspend(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

reason: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tenants.usage(...) -> TenantsUsage200Response

📝 Description

Facts only — no limits or billing state. Views count share exchanges plus authorized /v1/access grants, deduplicated across the two.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tenants.usage(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

period: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Documents

client.documents.list(...) -> DocumentsList200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.list(
    tenant_id="tenantId",
)

⚙️ Parameters

tenant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

state: typing.Optional[ListDocumentsRequestState]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.get(...) -> DocumentsGet200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.get(
    tenant_id="tenantId",
    id="id",
)

⚙️ Parameters

tenant_id: str

id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.delete(...)

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.delete(
    tenant_id="tenantId",
    id="id",
)

⚙️ Parameters

tenant_id: str

id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.commit(...) -> DocumentsCommit200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.commit(
    tenant_id="tenantId",
    id="id",
    sha256="sha256",
)

⚙️ Parameters

tenant_id: str

id: str

sha256: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.download(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.download(
    tenant_id="tenantId",
    id="id",
)

⚙️ Parameters

tenant_id: str

id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.thumbnail(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.thumbnail(
    tenant_id="tenantId",
    id="id",
)

⚙️ Parameters

tenant_id: str

id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.upload_proxy(...) -> DocumentsUploadProxy200Response

📝 Description

This bounded origin-mediated fallback must only be used after documents.init returns upload.kind=proxy. Auto mode prefers a presigned object-store PUT whenever available.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.upload_proxy(
    tenant_id="tenantId",
    id="id",
    file="example_file",
)

⚙️ Parameters

tenant_id: str

id: str

file: core.File

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.import_from(...) -> DocumentsImportFrom200Response

📝 Description

Default mode is synchronous and bounded: the response returns only after the transfer verified and committed (or failed). mode=async (connection sources only) answers 202 immediately and an in-process worker performs the transfer with leased, fenced retries; poll the document until ready/failed. The deployment import policy gates scheme, network range, and size; sources must declare a length. CloudPDF copies and owns the bytes — the source is never referenced in place. A 502 marks a retryable upstream failure: retry with the same idempotencyKey to resume the same document. URL sources are capabilities and never echoed back. Connection sources name operator-registered storage (bucket/prefix scope, allowed credential classes, and tenant bindings are deployment configuration); revision is provider-interpreted (S3 VersionId, GCS generation, Azure version id).

🔌 Usage

from cloudpdf import CloudPDFClient
from cloudpdf.documents import DocumentsImportFromRequestSource_Url

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.import_from(
    tenant_id="tenantId",
    source=DocumentsImportFromRequestSource_Url(
        url="url",
    ),
)

⚙️ Parameters

tenant_id: str

source: DocumentsImportFromRequestSource — Where CloudPDF pulls the bytes from. The two shapes differ in who supplies the authority to read, not in which storage vendor holds the file.

expected: typing.Optional[DocumentsImportFromRequestExpected] — Integrity pins, enforced when present. When absent, the server-observed values become authoritative.

metadata: typing.Optional[typing.Dict[str, typing.Any]]

idempotency_key: typing.Optional[str] — Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.

dedup_mode: typing.Optional[DocumentsImportFromRequestDedupMode] — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

doc_id: typing.Optional[str]

mode: typing.Optional[DocumentsImportFromRequestMode] — sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.init(...) -> DocumentsInit200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.documents.init(
    tenant_id="tenantId",
    content_length=1.1,
    content_sha256="contentSha256",
)

⚙️ Parameters

tenant_id: str

content_length: float

content_sha256: str

metadata: typing.Optional[typing.Dict[str, typing.Any]]

idempotency_key: typing.Optional[str]

dedup_mode: typing.Optional[DocumentsInitRequestDedupMode] — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.

doc_id: typing.Optional[str]

upload_ttl_sec: typing.Optional[float]

upload_preference: typing.Optional[DocumentsInitRequestUploadPreference]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Tokens

client.tokens.issue(...) -> TokensIssue200Response

📝 Description

kind "tenant" requires the API token — authority mints only downward. Mounted only when the deployment can sign (HS256 mode); asymmetric deployments mint with their own private key.

🔌 Usage

from cloudpdf import CloudPDFClient, TokensIssueRequest_Doc

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tokens.issue(
    tenant_id="tenantId",
    request=TokensIssueRequest_Doc(
        sub="sub",
        doc_id="docId",
        scope=[
            "scope"
        ],
        expires_in=1,
    ),
)

⚙️ Parameters

tenant_id: str

request: TokensIssueRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tokens.revoke(...)

📝 Description

Mounted only when the deployment enables token revocation.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.tokens.revoke(
    tenant_id="tenantId",
    jti="jti",
)

⚙️ Parameters

tenant_id: str

jti: str

reason: typing.Optional[str]

expires_at_seconds: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Annotations

client.doc.annotations.list_all(...) -> DocAnnotationsListAll200Response

📝 Description

Returns one entry per page plus the audit-log cursor for reconciling subsequent document events. Page order is unspecified; join by page (a PageRef) when display order matters.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.list_all(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.list(...) -> DocAnnotationsList200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.list(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.create(...) -> DocAnnotationsCreate200Response

📝 Description

Doc JWTs may instead carry collab scopes (annotations:create:self, …) that refine per-annotation authorship rules; the API token is exempt from both.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.create(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request: DocAnnotationsCreateRequest

idempotency_key: typing.Optional[str] — 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_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.delete(...) -> DocAnnotationsDelete200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.delete(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annot_key="annotKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

annot_key: str — The annotation's address on the page: obj:N, its indirect object number, or base:N for an annotation the uploaded file stored inline (without an object number of its own), the position it was born at in the page's /Annots. The name the annotation's ref carries for life.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.update(...) -> DocAnnotationsUpdate200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.update(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annot_key="annotKey",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request: DocAnnotationsUpdateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.read_appearance(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.read_appearance(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annot_key="annotKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.export_appearance(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.export_appearance(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    request={
        "string": {"key": "value"}
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request: DocAnnotationsExportAppearanceRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.flatten(...) -> DocAnnotationsFlatten200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.flatten(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request: DocAnnotationsFlattenRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.annotations.reorder(...) -> DocAnnotationsReorder200Response

🔌 Usage

from cloudpdf import CloudPDFClient, AnnotationRef_ObjectNumber, PageRef

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.annotations.reorder(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    refs=[
        AnnotationRef_ObjectNumber(
            page=PageRef(
                kind="objectNumber",
                object_number=1,
            ),
            object_number=1,
        )
    ],
    position="start",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

refs: typing.List[AnnotationRef]

position: AnnotationPosition

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Forms

client.doc.forms.list(...) -> DocFormsList200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.list(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.reorder_calculations(...) -> DocFormsReorderCalculations200Response

🔌 Usage

from cloudpdf import CloudPDFClient, FormFieldRef_ObjectNumber

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.reorder_calculations(
    doc_id="docId",
    layer_name="layerName",
    fields=[
        FormFieldRef_ObjectNumber(
            object_number=1,
        )
    ],
    position="start",
)

⚙️ Parameters

doc_id: str

layer_name: str

fields: typing.List[FormFieldRef]

position: FieldPosition

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.set_value(...) -> DocFormsSetValue200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.set_value(
    doc_id="docId",
    layer_name="layerName",
    field_key="fieldKey",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

field_key: str

request: DocFormsSetValueRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.reset(...) -> DocFormsReset200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.reset(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

refs: typing.Optional[typing.List[FormFieldRef]]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.delete_widget(...) -> DocFormsDeleteWidget200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.delete_widget(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annot_key="annotKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.update_widget(...) -> DocFormsUpdateWidget200Response

🔌 Usage

from cloudpdf import CloudPDFClient, WidgetPatch

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.update_widget(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annot_key="annotKey",
    patch=WidgetPatch(),
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

patch: WidgetPatch

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.forms.reorder_widgets(...) -> DocFormsReorderWidgets200Response

🔌 Usage

from cloudpdf import CloudPDFClient, AnnotationRef_ObjectNumber, PageRef

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.forms.reorder_widgets(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    widgets=[
        AnnotationRef_ObjectNumber(
            page=PageRef(
                kind="objectNumber",
                object_number=1,
            ),
            object_number=1,
        )
    ],
    position="start",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

widgets: typing.List[AnnotationRef]

position: AnnotationPosition

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Metadata

client.doc.metadata.get(...) -> DocMetadataGet200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.metadata.get(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Pages

client.doc.pages.set_scale(...) -> DocPagesSetScale200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.set_scale(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

measure: typing.Optional[DocPagesSetScaleRequestMeasure]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.viewports(...) -> DocPagesViewports200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.viewports(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
)

⚙️ Parameters

doc_id: str

layer_name: str

page_key: str — The page's address, obj:N: the page's indirect object number, the durable identity every PageLayout.ref carries. Mirrors annotKey and fieldKey.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.delete(...) -> DocPagesDelete200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.delete(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesDeleteRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.extract(...) -> typing.Iterator[bytes]

📝 Description

A read, not a mutation: the source document is untouched and no event is published. Body is {"pages": PageRef[]}; the response body is the new PDF.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.extract(
    doc_id="docId",
    layer_name="layerName",
    request={
        "string": {"key": "value"}
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesExtractRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.flatten(...) -> DocPagesFlatten200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.flatten(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesFlattenRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.insert(...) -> DocPagesInsert200Response

📝 Description

Multipart: a JSON body part {"position"?: PagePosition, "resources": {"source": "<key>"}} (position omitted → the end), and the standalone PDF whose pages are copied in as the part resource:<key>. The inserted copies get fresh page object numbers, returned in insertion order.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.insert(
    doc_id="docId",
    layer_name="layerName",
    file="example_file",
)

⚙️ Parameters

doc_id: str

layer_name: str

file: core.File

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.insert_blank(...) -> DocPagesInsertBlank200Response

📝 Description

Body is {"size": {"width", "height"}, "count"?, "position"?} — size in PDF points, count in [1, 100], position a PagePosition (omitted → the end).

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.insert_blank(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesInsertBlankRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.set_name(...) -> DocPagesSetName200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.set_name(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesSetNameRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.remove_name(...) -> DocPagesRemoveName200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.remove_name(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesRemoveNameRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.reorder(...) -> DocPagesReorder200Response

🔌 Usage

from cloudpdf import CloudPDFClient, PageRef

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.reorder(
    doc_id="docId",
    layer_name="layerName",
    pages=[
        PageRef(
            kind="objectNumber",
            object_number=1,
        )
    ],
    position="start",
)

⚙️ Parameters

doc_id: str

layer_name: str

pages: typing.List[PageRef]

position: PagePosition

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.pages.rotate(...) -> DocPagesRotate200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.pages.rotate(
    doc_id="docId",
    layer_name="layerName",
    request={
        "key": "value"
    },
)

⚙️ Parameters

doc_id: str

layer_name: str

request: DocPagesRotateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Redactions

client.doc.redactions.apply(...) -> DocRedactionsApply200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.redactions.apply(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

pages: typing.Optional[typing.List[PageRef]]

annotations: typing.Optional[typing.List[AnnotationRef]]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Signatures

client.doc.signatures.list(...) -> DocSignaturesList200Response

📝 Description

Describes the bytes the layer is over: the base version's signatures plus the layer's own edits as the last revision. Signed bytes (contents, digests, revision prefixes) are served per base version under /versions.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.signatures.list(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.signatures.cancel(...) -> DocSignaturesCancel200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.signatures.cancel(
    doc_id="docId",
    layer_name="layerName",
    signing_id="signingId",
)

⚙️ Parameters

doc_id: str

layer_name: str

signing_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.signatures.complete(...) -> DocSignaturesComplete200Response

📝 Description

cms is the detached CMS over the prepared digest, base64. expectedVersion must be what prepare returned. Idempotent by signing id: the same CMS again answers already-completed. Every layer of the document then sits over the new version; refetch the manifest after a completion.

🔌 Usage

from cloudpdf import CloudPDFClient
from cloudpdf.doc.signatures import DocSignaturesCompleteRequestExpectedVersion

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.signatures.complete(
    doc_id="docId",
    layer_name="layerName",
    signing_id="signingId",
    cms="cms",
    expected_version=DocSignaturesCompleteRequestExpectedVersion(
        base_sha256="baseSha256",
        edits_version=1,
    ),
)

⚙️ Parameters

doc_id: str

layer_name: str

signing_id: str

cms: str

expected_version: DocSignaturesCompleteRequestExpectedVersion

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.signatures.analysis(...) -> DocSignaturesAnalysis200Response

📝 Description

Exactly one of since.signature=<index> or since.revision=<index>; the layer's pending edits are the end. level=fill|annotate|lta|none evaluates exploratorily and never becomes a verdict. For history between two base revisions use the version analysis.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.signatures.analysis(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

since_signature: typing.Optional[int]

since_revision: typing.Optional[int]

level: typing.Optional[AnalysisSignaturesRequestLevel]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.signatures.prepare(...) -> DocSignaturesPrepare200Response

📝 Description

Multipart: a JSON body part (field, subFilter, digest, contentsSize, signer, certify, lock), naming the appearance PDF it may carry as resources: { appearance: '<key>' }, and that PDF as the part resource:<key>. A certification (certify.permission) additionally requires doc.sign.certify. The layer is read-only until the signing completes, is cancelled, or expires (15 minutes). A layer behind the document head cannot sign (StaleBase).

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.signatures.prepare(
    doc_id="docId",
    layer_name="layerName",
    file="example_file",
)

⚙️ Parameters

doc_id: str

layer_name: str

file: core.File

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Versions

client.doc.versions.list(...) -> DocVersionsList200Response

📝 Description

Every completed signature publishes a new version. Never cached: the list grows.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.list(
    doc_id="docId",
)

⚙️ Parameters

doc_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.analysis(...) -> DocVersionsAnalysis200Response

📝 Description

Exactly one of since.signature / since.revision; until=<revision> defaults to the last. The same answer for every layer and every caller.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.analysis(
    doc_id="docId",
    sha="sha",
)

⚙️ Parameters

doc_id: str

sha: str

since_signature: typing.Optional[int]

since_revision: typing.Optional[int]

level: typing.Optional[AnalysisVersionsRequestLevel]

until: typing.Optional[int]

policy: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.download(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.download(
    doc_id="docId",
    sha="sha",
)

⚙️ Parameters

doc_id: str

sha: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.revision(...) -> typing.Iterator[bytes]

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.revision(
    doc_id="docId",
    sha="sha",
    index=1,
)

⚙️ Parameters

doc_id: str

sha: str

index: int

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.signatures(...) -> DocVersionsSignatures200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.signatures(
    doc_id="docId",
    sha="sha",
)

⚙️ Parameters

doc_id: str

sha: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.signature_contents(...) -> typing.Iterator[bytes]

📝 Description

fieldKey is the field's fully qualified name, token-text encoded (the same encoding attachment keys use).

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.signature_contents(
    doc_id="docId",
    sha="sha",
    field_key="fieldKey",
)

⚙️ Parameters

doc_id: str

sha: str

field_key: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.doc.versions.signature_digest(...) -> typing.Iterator[bytes]

📝 Description

What a CMS verifier compares its message digest to.

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.versions.signature_digest(
    doc_id="docId",
    sha="sha",
    field_key="fieldKey",
    algorithm="sha1",
)

⚙️ Parameters

doc_id: str

sha: str

field_key: str

algorithm: SignatureDigestVersionsRequestAlgorithm

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Doc Metadata Custom

client.doc.metadata.custom.get(...) -> DocMetadataCustomGet200Response

🔌 Usage

from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.doc.metadata.custom.get(
    doc_id="docId",
    layer_name="layerName",
)

⚙️ Parameters

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

FilesExpand file tree

reference.md

Latest commit

History

reference.md

File metadata and controls

Reference

Deployment

🔌 Usage

⚙️ Parameters

Doc

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

Shares

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

Tenants

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Documents

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

🔌 Usage

⚙️ Parameters

Tokens