Initialize upload

POST/v1/tenants/{tenantId}/documents/initv3.0.0-next.9

Begin an upload: create (or resume/dedupe) a pending document and issue upload access.

Authentication#

Any one of these credentials is accepted.

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.

Required scopedocs.create

Parameters#

tenantIdpathstringrequired

Request body#

application/jsonDocumentsInitRequestrequired

contentLengthnumberrequired

contentSha256stringrequired

metadataobject

idempotencyKeystring

dedupMode"always-create" | "reuse-existing"

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.

docIdstring

uploadTtlSecnumber

uploadPreference"auto" | "presigned" | "proxy"

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

{
  "contentLength": 1,
  "contentSha256": "contentSha256"
}

SDK examples#

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

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

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

await client.documents.init({
  tenantId: "tenantId",
  contentLength: 1.1,
  contentSha256: "contentSha256"
});

Responses#

200OK

application/jsonDocumentsInit200Response

tag =

tag"created"

documentobject

idstring

tenantIdstring

state"pending" | "ready" | "failed" | "deleting"

baseShastring

storageSizeBytesnumber

metadataobject

idempotencyKeystring

failureReasonstring

thumbnailState"pending" | "ready" | "locked" | "failed"optional

thumbnailUrlstringoptional

createdAtnumber

updatedAtnumber

createdBystring

upload"presigned" | "proxy"

kind =

kind"presigned"

presignedobject

urlstring

headersobject

method"PUT"

expiresAtnumber

keystring

400Bad request

application/jsonDocumentsInit400Response

errorobject

codestring

messagestring

defaultError

application/jsonAdminErrorPayload

errorobject

codestring

messagestring