Skip to content

Latest commit

Β 

History

History
8760 lines (5997 loc) Β· 127 KB

reference.md

File metadata and controls

8760 lines (5997 loc) Β· 127 KB

Reference

Deployment

client.deployment.license_status() -> DeploymentLicenseStatusResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.deployment.license_status()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.deployment.modules() -> DeploymentModulesResponse

πŸ“ Description

What each module declares, for a dashboard or a script that lists modules, offers their permissions in its dialogs and shows their meters. Which tenants may use one is in their features (tenants.get); what it costs, if anything, is the operator's.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.deployment.modules()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Doc

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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(...) -> DocChangesResponse

πŸ“ 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, outline doc.outline.modify, pages doc.pages.assemble, embedded files doc.attachments.modify. Bytes (a stamp's drawing, an attached file, a signature's artwork, a PDF whose pages come in) 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.environment import CloudPDFEnvironment
from cloudpdf.doc import DocChangesRequestChangesItem

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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]

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.download(...) -> typing.Iterator[bytes]

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.download_link(...) -> DocDownloadLinkResponse

πŸ“ Description

The link opens the layer as it is when created: once the layer changes, it answers 404, so create it right before handing it over. It downloads that one file and nothing else, and a password-protected document is checked when the link is created. Deployments that verify tokens with their own keys (JWKS) mint links on their backend: a doc token with layer_name, a download: { docVersion, mode: "incremental" } claim and a short exp, passed as link on the versioned download URL.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

expires_in_seconds: typing.Optional[int]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

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.text(...) -> DocTextResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

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.

Grants

client.grants.exchange(...) -> GrantsExchangeResponse

πŸ“ Description

Unauthenticated, but requires a browser Origin header, checked against the grant allowlist. Unknown, deleted, paused and archived grants are indistinguishable (404). Passphrase-protected grants return 422 GrantPassphraseRequired until passphrase is supplied. A grant that asks its visitors who they are on open returns 422 VisitorIdentityRequired until the required answers are given; error.details carries fields (what the grant asks), missing, invalid, purpose and privacyUrl. A grant that asks before the first change issues the session at once with visitor.identityRequest, and writes answer 403 VisitorIdentityRequired with the same details until the visitor exchanges again with their answers. Answers that can not be taken answer 422 on any grant. Mounted only when the deployment can sign (HS256 mode).

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.exchange(
    grant="grant",
)

βš™οΈ Parameters

grant: str

passphrase: typing.Optional[str]

visitor_handle: typing.Optional[str]

restart: typing.Optional[bool]

visitor_identity: typing.Optional[GrantsExchangeRequestVisitorIdentity]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.list(...) -> GrantsListResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

doc_id: typing.Optional[str]

archived: typing.Optional[bool]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.create(...) -> GrantsCreateResponse

πŸ“ Description

The returned id is what a link page or an embed opens. Its scope gives only document permissions the caller holds itself, as tokens.issue does. 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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

doc_id: str

scope: typing.List[str]

name: typing.Optional[str]

layer_mode: typing.Optional[GrantsCreateRequestLayerMode]

layer_name: typing.Optional[str]

keep_visitor_layers: typing.Optional[bool]

visitor_idle_seconds: typing.Optional[int]

visitor_identity: typing.Optional[GrantsCreateRequestVisitorIdentity]

identity: typing.Optional[Identity]

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

passphrase: typing.Optional[str]

session_ttl_seconds: typing.Optional[int]

expires_at: typing.Optional[datetime.datetime]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.get(...) -> GrantsGetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.get(
    tenant_id="tenantId",
    grant_id="grantId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.delete(...)

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.delete(
    tenant_id="tenantId",
    grant_id="grantId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.update(...) -> GrantsUpdateResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.update(
    tenant_id="tenantId",
    grant_id="grantId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

name: typing.Optional[str]

layer_mode: typing.Optional[GrantsUpdateRequestLayerMode]

layer_name: typing.Optional[str]

keep_visitor_layers: typing.Optional[bool]

visitor_idle_seconds: typing.Optional[int]

visitor_identity: typing.Optional[GrantsUpdateRequestVisitorIdentity]

identity: typing.Optional[Identity]

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

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

passphrase: typing.Optional[str]

session_ttl_seconds: typing.Optional[int]

disabled: typing.Optional[bool]

expires_at: typing.Optional[datetime.datetime]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.archive(...) -> GrantsArchiveResponse

πŸ“ Description

Archiving is final: an archived grant never exchanges again, and to give access again you create a new grant. Pausing (disabled) is the reversible stop. An archived grant no longer counts as using its shared layer, so that layer can be deleted.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.archive(
    tenant_id="tenantId",
    grant_id="grantId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Tenants

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.tenants.list()

βš™οΈ Parameters

limit: typing.Optional[int]

cursor: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

id: str

name: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.tenants.update(...) -> TenantsUpdateResponse

πŸ“ Description

A feature names an installed module; any other id is a 400. A module route answers a tenant without its feature 403 FeatureNotEnabled, and one whose feature is stopped 402 FeatureStopped (details.feature, details.stopped). Other replicas apply a change within 30 seconds.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, TenantFeature
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.tenants.update(
    tenant_id="tenantId",
    features=[
        TenantFeature(
            id="id",
        )
    ],
)

βš™οΈ Parameters

tenant_id: str

features: typing.List[TenantFeature]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.tenants.resume(...)

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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(...) -> TenantsUsageResponse

πŸ“ Description

Facts only β€” no limits or billing state. Views count grant exchanges plus authorized /v1/access requests, deduplicated across the two.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

period: typing.Optional[str]

from: typing.Optional[str]

to: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Documents

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

state: typing.Optional[ListDocumentsRequestState] β€” Only documents in this state. Without it, every state except deleting.

q: typing.Optional[str] β€” Only documents whose name contains this text, ignoring case.

folder_id: typing.Optional[str] β€” Only documents directly in this folder (root: the top level). Without it, documents in every folder.

sort: typing.Optional[ListDocumentsRequestSort] β€” createdAt (default), name (ignoring case), or size (stored bytes; 0 while pending).

order: typing.Optional[ListDocumentsRequestOrder] β€” Defaults to the reading order of the sort: A to Z for name, newest and largest first otherwise.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.get(
    tenant_id="tenantId",
    doc_id="docId",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.documents.delete(...)

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.delete(
    tenant_id="tenantId",
    doc_id="docId",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.documents.update(...) -> DocumentsUpdateResponse

πŸ“ Description

A document that is being deleted answers 404.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.update(
    tenant_id="tenantId",
    doc_id="docId",
    name="name",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

name: str β€” What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

An upload token commits only the documents it started; any other document answers 404.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

doc_id: str

sha256: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.download(
    tenant_id="tenantId",
    doc_id="docId",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.thumbnail(
    tenant_id="tenantId",
    doc_id="docId",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ 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. An upload token sends files only to the documents it started.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

doc_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.environment import CloudPDFEnvironment
from cloudpdf.documents import DocumentsImportFromRequestSource_Url

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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.

name: typing.Optional[str] β€” What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

folder_id: typing.Optional[str] β€” A folder id, or root for the top level.

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(...) -> DocumentsInitResponse

πŸ“ Description

With an upload token, the document goes into the token's folder with the token's metadata, whatever the request says; sizeBytes must be within the token's maxBytes, and the token makes at most maxFiles documents (403 after). docId, idempotencyKey and dedupMode reuse-existing are refused (400): each could reach a document the token didn't make.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.init(
    tenant_id="tenantId",
    size_bytes=1,
    content_sha256="contentSha256",
)

βš™οΈ Parameters

tenant_id: str

size_bytes: int

content_sha256: str

name: typing.Optional[str] β€” What people call the document: shown in dashboards, searched and sorted by. 1 to 255 characters, no control characters, no leading or trailing whitespace. Names need not be unique.

folder_id: typing.Optional[str] β€” A folder id, or root for the top level.

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_seconds: typing.Optional[int]

upload_preference: typing.Optional[DocumentsInitRequestUploadPreference]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Folders

client.folders.list(...) -> FoldersListResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

parent_id: typing.Optional[str] β€” Only the folders directly in this folder (root: the top level). Without it, every folder.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.folders.create(...) -> FoldersCreateResponse

πŸ“ Description

409 Conflict carries details.reason: name-taken (a sibling has the name, ignoring case; details.name) or too-deep (folders nest at most 100 levels; details.maxDepth). 404 when the parent folder does not exist.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.folders.create(
    tenant_id="tenantId",
    name="name",
)

βš™οΈ Parameters

tenant_id: str

name: str β€” What people call the folder: 1 to 255 characters, no control characters, no leading or trailing whitespace, and unique among the folder's siblings, ignoring case.

parent_id: typing.Optional[str] β€” A folder id, or root for the top level.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.folders.get(...) -> FoldersGetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.folders.get(
    tenant_id="tenantId",
    folder_id="folderId",
)

βš™οΈ Parameters

tenant_id: str

folder_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.folders.delete(...)

πŸ“ Description

Without recursive, a folder with anything inside is refused: 409 Conflict with details.reason not-empty and what it holds, counted over every level below, in details.folders and details.documents. With recursive=true, the folder and every folder under it go at once, and every document in them stops opening, leaves every list and stops answering its grants at once; their stored files and grants are removed in the background. Uploads into those folders that have not committed cannot commit.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.folders.delete(
    tenant_id="tenantId",
    folder_id="folderId",
)

βš™οΈ Parameters

tenant_id: str

folder_id: str

recursive: typing.Optional[bool] β€” true deletes everything in the folder too. Never the default.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.folders.update(...) -> FoldersUpdateResponse

πŸ“ Description

409 Conflict with details.reason name-taken when a sibling has the name, ignoring case.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.folders.update(
    tenant_id="tenantId",
    folder_id="folderId",
    name="name",
)

βš™οΈ Parameters

tenant_id: str

folder_id: str

name: str β€” What people call the folder: 1 to 255 characters, no control characters, no leading or trailing whitespace, and unique among the folder's siblings, ignoring case.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.folders.move_into(...)

πŸ“ Description

Up to 1,000 ids in total. A folder moves with everything in it. 404 NotFound names the ids that do not exist or are being deleted in details.docIds and details.folderIds. 409 Conflict carries details.reason: cycle (the destination is a moved folder or inside one; details.folderId), too-deep (the move would nest folders deeper than 100 levels; details.maxDepth) or name-taken (a moved folder's name is taken in the destination, ignoring case; details.name).

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.folders.move_into(
    tenant_id="tenantId",
    folder_id="folderId",
)

βš™οΈ Parameters

tenant_id: str

folder_id: str β€” A folder id, or root for the top level.

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

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

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Tokens

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

πŸ“ Description

Authority mints only downward: kind "doc" gives only document permissions the caller holds itself, kind "tenant" requires the API token, and kind "upload" requires docs.create instead of tokens.issue-doc, since an upload token can do only what docs.create allows. Mounted only when the deployment can sign (HS256 mode); asymmetric deployments mint with their own private key.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, TokensIssueRequest_Doc
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.tokens.issue(
    tenant_id="tenantId",
    request=TokensIssueRequest_Doc(
        sub="sub",
        doc_id="docId",
        scope=[
            "scope"
        ],
        expires_in_seconds=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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

tenant_id: str

jti: str

reason: typing.Optional[str]

expires_at: typing.Optional[datetime.datetime]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Doc Annotations

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

πŸ“ 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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.annotations.list(...) -> DocAnnotationsListResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

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.annotations.create(...) -> DocAnnotationsCreateResponse

πŸ“ 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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

request: DocAnnotationsCreateRequest

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.

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(...) -> DocAnnotationsDeleteResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ 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 annotationKey and fieldKey.

annotation_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.

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.

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.update(...) -> DocAnnotationsUpdateResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.annotations.update(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annotation_key="annotationKey",
    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 annotationKey and fieldKey.

annotation_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: DocAnnotationsUpdateRequest

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.

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.read_appearance(...) -> typing.Iterator[bytes]

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ 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 annotationKey and fieldKey.

annotation_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.

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.annotations.read_file(...) -> typing.Iterator[bytes]

πŸ“ Description

A file that decodes past the server's limit is refused (PayloadTooLarge).

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.annotations.read_file(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annotation_key="annotationKey",
)

βš™οΈ 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 annotationKey and fieldKey.

annotation_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.

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.annotations.export_appearance(...) -> typing.Iterator[bytes]

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

request: DocAnnotationsExportAppearanceRequest

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.annotations.flatten(...) -> DocAnnotationsFlattenResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

request: DocAnnotationsFlattenRequest

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.

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.reorder(...) -> DocAnnotationsReorderResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, AnnotationRef_ObjectNumber, PageRef
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

refs: typing.List[AnnotationRef]

position: AnnotationPosition

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.

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.

Doc Attachments

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

πŸ“ Description

A file that decodes past the server's limit is refused (PayloadTooLarge).

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

file_key: str β€” The embedded file's name-tree key (its ref.key), token-text encoded, as fieldKey is.

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.attachments.list(...) -> DocAttachmentsListResponse

πŸ“ Description

A file-attachment annotation's file is listed with the annotation; read its bytes with doc.annotations.readFile.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

Doc Fonts

client.doc.fonts.list(...) -> DocFontsListResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.fonts.resolve(...) -> DocFontsResolveResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, FontResolveRun
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.fonts.resolve(
    doc_id="docId",
    layer_name="layerName",
    runs=[
        FontResolveRun(
            text="text",
        )
    ],
)

βš™οΈ Parameters

doc_id: str

layer_name: str

request: DocFontsResolveRequest

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.

Doc Forms

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.forms.reorder_calculations(...) -> DocFormsReorderCalculationsResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, FormFieldRef_ObjectNumber
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

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.

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.forms.set_value(...) -> DocFormsSetValueResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

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.

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.forms.reset(...) -> DocFormsResetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

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.

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

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ 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 annotationKey and fieldKey.

annotation_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.

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.

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.forms.update_widget(...) -> DocFormsUpdateWidgetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, WidgetPatch
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.forms.update_widget(
    doc_id="docId",
    layer_name="layerName",
    page_key="pageKey",
    annotation_key="annotationKey",
    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 annotationKey and fieldKey.

annotation_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.

patch: WidgetPatch

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.

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.forms.reorder_widgets(...) -> DocFormsReorderWidgetsResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient, AnnotationRef_ObjectNumber, PageRef
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

widgets: typing.List[AnnotationRef]

position: AnnotationPosition

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.

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.

Doc Metadata

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

Doc Outline

client.doc.outline.get(...) -> DocOutlineGetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

Doc Pages

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

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.

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.

measure: typing.Optional[DocPagesSetScaleRequestMeasure]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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 annotationKey and fieldKey.

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.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[], "flatten"?: {"usage"?: "display" | "print"}, "includeAnnotations"?: boolean, "includeFormFields"?: boolean}; the response body is the new PDF. With flatten the copy is the pages as they draw for usage ("print": a print copy): the annotations and form fields painted in, nothing interactive left, layers in their state for the usage. A flattened copy takes doc.download or doc.download.flattened, and paints only what the caller may read; includeAnnotations and includeFormFields choose what it paints, and are refused without flatten.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

request: DocPagesExtractRequest

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.pages.flatten(...) -> DocPagesFlattenResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

request: DocPagesFlattenRequest

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.

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.pages.set_name(...) -> DocPagesSetNameResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

request: DocPagesSetNameRequest

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.

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.pages.remove_name(...) -> DocPagesRemoveNameResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

request: DocPagesRemoveNameRequest

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.

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.

Doc Redactions

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

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.

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(...) -> DocSignaturesListResponse

πŸ“ 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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.signatures.cancel(...) -> DocSignaturesCancelResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

signing_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.signatures.complete(...) -> DocSignaturesCompleteResponse

πŸ“ 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. The new version is the layer's own: only this layer moves to it, and the document and every other layer stay as they were. Refetch the manifest after a completion.

πŸ”Œ Usage

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

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

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.signatures.analysis(...) -> DocSignaturesAnalysisResponse

πŸ“ 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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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]

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.signatures.prepare(...) -> DocSignaturesPrepareResponse

πŸ“ 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 document timestamp (kind: 'timestamp') may leave field out, since 3.3: the engine then makes a field of no size for it, under a name no other field has, and the answer names it in field. That needs doc.sign for the document. The signature is made over the layer's own base: the upload, or the version its last signature made.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

file: core.File

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.signatures.validation_info(...) -> DocSignaturesValidationInfoResponse

πŸ“ Description

Each entry is one DER object, base64. It reads the layer as it is now, so entries stored and not yet sealed by a signature are among them. Arrived in 3.3.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.signatures.add_validation_info(...) -> DocSignaturesAddValidationInfoResponse

πŸ“ Description

Each entry is one DER object of at most 16 MiB, base64. An entry the file already holds, byte for byte, is not stored again: added counts the new ones. An entry that is not one DER object fails the request and nothing is stored; the error names it, as in certificates[1]. The server stores what it is given and asks no certificate authority: collect the answers first. It needs doc.sign for the document, not for a group of fields, and is refused after a certification that allows no changes. It cannot be undone, and it leaves undo for earlier changes as it was. Arrived in 3.3.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

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.

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

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

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

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Doc Versions

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

πŸ“ Description

Every completed signature makes a new version of its layer; another layer's versions are never listed. Never cached: the list grows.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.versions.analysis(...) -> DocVersionsAnalysisResponse

πŸ“ Description

Exactly one of since.signature / since.revision; until=<revision> defaults to the last. The same answer for every caller. A version never changes, but the rules that judge it can: with engine, the analysis value of the layer's head, a settled answer is immutable. Without it, or with another value, the answer is this server's own, with no-store and the current value in EmbedPDF-Engine.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: str

since_signature: typing.Optional[int]

since_revision: typing.Optional[int]

level: typing.Optional[AnalysisVersionsRequestLevel]

until: typing.Optional[int]

engine: typing.Optional[str] β€” The analysis engine value from the layer's head (engine.analysis): the rules the answer is judged with. With it, a settled answer is cached.

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.versions.download(...) -> typing.Iterator[bytes]

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: 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.versions.revision(...) -> typing.Iterator[bytes]

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.versions.revision(
    doc_id="docId",
    layer_name="layerName",
    sha256="sha256",
    index=1,
)

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: str

index: int

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.versions.signatures(...) -> DocVersionsSignaturesResponse

πŸ“ Description

A version never changes, but what the server reads from it can: with engine, the signatures value of the layer's head, the answer is immutable. Without it, or with another value, the answer is this server's own, with no-store and the current value in EmbedPDF-Engine.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: str

engine: typing.Optional[str] β€” The signatures engine value from the layer's head (engine.signatures): what the answer is computed with besides the file. With it, the answer is cached.

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.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
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.versions.signature_contents(
    doc_id="docId",
    layer_name="layerName",
    sha256="sha256",
    field_key="fieldKey",
)

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: str

field_key: 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.versions.signature_digest(...) -> typing.Iterator[bytes]

πŸ“ Description

What a CMS verifier compares its message digest to.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: str

sha256: str

field_key: str

algorithm: SignatureDigestVersionsRequestAlgorithm

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.

Doc Fonts Programs

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

πŸ“ Description

A document token needs any one of the listed capabilities: one that may write text in the document. A file the list says can't be downloaded (canDownload: false) is not found.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.fonts.programs.download(
    doc_id="docId",
    layer_name="layerName",
    display_sha256="displaySha256",
)

βš™οΈ Parameters

doc_id: str

layer_name: str

display_sha256: 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.fonts.programs.get(...) -> DocFontsProgramsGetResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.doc.fonts.programs.get(
    doc_id="docId",
    layer_name="layerName",
    display_sha256="displaySha256",
)

βš™οΈ Parameters

doc_id: str

layer_name: str

display_sha256: 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.

Doc Metadata Custom

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

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

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

βš™οΈ Parameters

doc_id: str

layer_name: 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.

Documents Layers

client.documents.layers.list(...) -> DocumentsLayersListResponse

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.layers.list(
    tenant_id="tenantId",
    doc_id="docId",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

grant_id: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.documents.layers.delete(...)

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.documents.layers.delete(
    tenant_id="tenantId",
    doc_id="docId",
    layer_name="layerName",
)

βš™οΈ Parameters

tenant_id: str

doc_id: str

layer_name: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Grants Visitors

client.grants.visitors.list(...) -> GrantsVisitorsListResponse

πŸ“ Description

An archived grant's visitors are listed too.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.visitors.list(
    tenant_id="tenantId",
    grant_id="grantId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

limit: typing.Optional[int]

cursor: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.grants.visitors.delete(...)

πŸ“ Description

Their handle brings them back as a new visitor, who is asked again. Deleting a visitor already deleted changes nothing.

πŸ”Œ Usage

from cloudpdf import CloudPDFClient
from cloudpdf.environment import CloudPDFEnvironment

client = CloudPDFClient(
    token="<token>",
    environment=CloudPDFEnvironment.SAAS,
)

client.grants.visitors.delete(
    tenant_id="tenantId",
    grant_id="grantId",
    visitor_id="visitorId",
)

βš™οΈ Parameters

tenant_id: str

grant_id: str

visitor_id: str

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.