--- title: "CloudPDF API reference" description: "Complete reference for the CloudPDF server API, with examples for all seven official SDKs." source: "https://www.cloudpdf.com/docs/api-reference" --- # CloudPDF API reference The CloudPDF server API is what your **backend** calls: it gets documents in and mints the short-lived tokens your viewer opens with. The browser never talks to this API directly. Every operation below is generated from the same OpenAPI contract that generates the official SDKs, so the reference cannot drift from the wire. > The current API and SDK line is a preview. Endpoint pages display the exact canonical version, > and your SDK language is remembered across the whole reference — pick it once below. ## Install Seven official SDKs, all generated from the contract below. Your choice here is remembered for every example in the reference. **TypeScript** ```sh npm install @cloudpdf/sdk@next ``` **Python** ```sh pip install cloudpdf ``` **PHP** ```sh composer require cloudpdf/sdk ``` **.NET** ```sh dotnet add package CloudPDF ``` **Go** ```sh go get github.com/embedpdf/cloudpdf-sdk-go/v3 ``` **Java** ```groovy implementation 'com.cloudpdf:sdk' ``` **Ruby** ```sh gem install cloudpdf ``` ## Get access ### Managed SaaS On managed CloudPDF **your account is a tenant** — tenants and deployment configuration are operated by the platform, so the sections marked *Self-hosted* below don't apply to you. Your API key from the [dashboard](https://app.cloudpdf.com) is a **tenant token**: it can manage documents and mint document tokens under your account, and nothing else. Use it as the `token` in every example in this reference. ### Self-hosted On a self-hosted deployment **you are the operator**. Configure the root credential on the server: ```sh CLOUDPDF_API_AUTH_TOKENS= ``` The API token is valid on every surface — including creating the [tenants](https://www.cloudpdf.com/docs/api-reference/tenants/create) that namespace your customers' documents. Use it as the `token` in every example, or mint scoped [tenant tokens](https://www.cloudpdf.com/docs/api-reference/authentication#tenant-tokens) for your services. ## Getting a document on screen Three steps, and only the last one runs in a browser. 1. **[Initialize an upload](https://www.cloudpdf.com/docs/api-reference/documents/init)** — request upload access, transfer the file using the returned instructions, then [commit the upload](https://www.cloudpdf.com/docs/api-reference/documents/commit). 2. **[Issue a document token](https://www.cloudpdf.com/docs/api-reference/tokens/issue)** — a short-lived JWT pinned to one document, carrying exactly the capabilities that user should have. 3. **Open it** — hand that token to the viewer or headless components. See [Engine: getting started](https://www.cloudpdf.com/docs/engine/getting-started). Steps 1–2 are the API surface documented here. Step 3 is the client SDK. ## Authentication Three credentials, and **authority mints only downward**. Each rung is weaker than the one above it, and only the last one ever reaches a browser. - **API token** — The deployment's static root credential (CLOUDPDF\_API\_AUTH\_TOKENS), valid on every surface. - **Tenant token** — Delegated tenant JWT, valid only under its own /v1/tenants/\{tenantId}/ subtree — the path tenant must equal the token's tenant\_id. Doc-scoped viewer tokens are rejected on every admin route. - **Document token** — Doc-scoped JWT, valid only on the /v1/docs/\{docId} subtree it names, gated by the capability scopes it carries (each operation's x-required-capability). [How authentication works →](https://www.cloudpdf.com/docs/api-reference/authentication) — minting, signing modes, revocation, and the full capability tables. ## Resources ### Deployment (self-hosted) - `GET` [License status](https://www.cloudpdf.com/docs/api-reference/deployment/license-status) ### Tenants - `GET` [List tenants](https://www.cloudpdf.com/docs/api-reference/tenants/list) - `POST` [Create tenant](https://www.cloudpdf.com/docs/api-reference/tenants/create) - `GET` [Get tenant](https://www.cloudpdf.com/docs/api-reference/tenants/get) - `DELETE` [Delete tenant](https://www.cloudpdf.com/docs/api-reference/tenants/delete) - `POST` [Resume tenant](https://www.cloudpdf.com/docs/api-reference/tenants/resume) - `POST` [Suspend tenant](https://www.cloudpdf.com/docs/api-reference/tenants/suspend) - `GET` [Tenant usage](https://www.cloudpdf.com/docs/api-reference/tenants/usage) ### Tenant documents - `GET` [List documents](https://www.cloudpdf.com/docs/api-reference/documents/list) - `GET` [Get document](https://www.cloudpdf.com/docs/api-reference/documents/get) - `DELETE` [Delete document](https://www.cloudpdf.com/docs/api-reference/documents/delete) - `POST` [Commit upload](https://www.cloudpdf.com/docs/api-reference/documents/commit) - `GET` [Download document](https://www.cloudpdf.com/docs/api-reference/documents/download) - `GET` [Get thumbnail](https://www.cloudpdf.com/docs/api-reference/documents/thumbnail) - `POST` [Upload document through the origin](https://www.cloudpdf.com/docs/api-reference/documents/upload-proxy) - `POST` [Import document](https://www.cloudpdf.com/docs/api-reference/documents/import-from) - `POST` [Initialize upload](https://www.cloudpdf.com/docs/api-reference/documents/init) ### Tokens - `POST` [Issue token](https://www.cloudpdf.com/docs/api-reference/tokens/issue) - `POST` [Revoke token](https://www.cloudpdf.com/docs/api-reference/tokens/revoke) ### Shares - `POST` [Exchange share token](https://www.cloudpdf.com/docs/api-reference/shares/exchange) - `GET` [List shares](https://www.cloudpdf.com/docs/api-reference/shares/list) - `POST` [Create share](https://www.cloudpdf.com/docs/api-reference/shares/create) - `GET` [Get share](https://www.cloudpdf.com/docs/api-reference/shares/get) - `PATCH` [Update share](https://www.cloudpdf.com/docs/api-reference/shares/update) - `DELETE` [Revoke share](https://www.cloudpdf.com/docs/api-reference/shares/delete) ### Document operations - `GET` [Open document](https://www.cloudpdf.com/docs/api-reference/document-operations/head) - `GET` [Download PDF](https://www.cloudpdf.com/docs/api-reference/document-operations/download) - `GET` [Get manifest](https://www.cloudpdf.com/docs/api-reference/document-operations/manifest) - `GET` [Render page](https://www.cloudpdf.com/docs/api-reference/document-operations/render) - `GET` [Extract page text](https://www.cloudpdf.com/docs/api-reference/document-operations/text) ### Annotations - `GET` [List annotations](https://www.cloudpdf.com/docs/api-reference/document-operations/annotations/list) - `POST` [Create annotation](https://www.cloudpdf.com/docs/api-reference/document-operations/annotations/create) - `PATCH` [Update annotation](https://www.cloudpdf.com/docs/api-reference/document-operations/annotations/update) - `DELETE` [Delete annotation](https://www.cloudpdf.com/docs/api-reference/document-operations/annotations/delete) ### Forms - `GET` [Get form snapshot](https://www.cloudpdf.com/docs/api-reference/document-operations/forms/get) - `GET` [Export form data](https://www.cloudpdf.com/docs/api-reference/document-operations/forms/export-data) - `POST` [Import form data](https://www.cloudpdf.com/docs/api-reference/document-operations/forms/import-data) - `POST` [Reset form field](https://www.cloudpdf.com/docs/api-reference/document-operations/forms/reset) - `POST` [Set form value](https://www.cloudpdf.com/docs/api-reference/document-operations/forms/set-value) ### Metadata - `GET` [Get metadata](https://www.cloudpdf.com/docs/api-reference/document-operations/metadata/get) ### Pages - `POST` [Delete pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/delete) - `POST` [Extract pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/extract) - `POST` [Flatten pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/flatten) - `POST` [Insert pages from a PDF](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/insert) - `POST` [Insert blank pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/insert-blank) - `POST` [Move pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/move) - `POST` [Rotate pages](https://www.cloudpdf.com/docs/api-reference/document-operations/pages/rotate) ### Redactions - `POST` [Apply redactions](https://www.cloudpdf.com/docs/api-reference/document-operations/redactions/apply)