Templates

Create template

Creates a draft template owned by the user that minted the API key. Drafts are not renderable until published. The source is normalized through the same pipeline the app uses and should define a top-level #let render(...) entry function whose named parameters match the schema fields.

External ids are case-sensitive and stay reserved after a template is deleted.

post/v2/organizations/{organizationId}/templates

Request

  • Base URL: https://api.pdfs.build
  • URL: https://api.pdfs.build/v2/organizations/{organizationId}/templates
  • Auth: HTTP bearer

Request body

externalIdstring required

Organization-scoped template id you control. 1–128 ASCII letters, digits, ., _, ~ or -; . and .. are reserved. Case-sensitive.

namestring required

Display name.

descriptionstring
codestring required

Template source. Must define a top-level #let render(...) entry function. (typstCode is accepted as a legacy alias.)

schemaobject

JSON Schema describing the render data payload.

sampleDataobject

Example data that satisfies schema.

pageSettingsobject

Page size, margins and other layout settings.

schemaLockedboolean

Freeze the data contract at creation. Cannot be changed later. Rejected if sampleData contains fields the schema does not declare.

scopePathstring

Tenant scope for delegated agent access: zero or more segments, each 1–128 chars from the external-id charset and each ending in /, e.g. acct_9f3/entity_dubai/. Empty means unscoped — invisible to every delegated grant.

Example request

{
  "scopePath": "acct_9f3/entity_dubai/"
}

Response

The created draft, including both the generated internalId and your externalId.

internalIdstring required

Generated, immutable. What v1 URLs and the embedded SDK address.

externalIdstring required

Organization-scoped template id you control. 1–128 ASCII letters, digits, ., _, ~ or -; . and .. are reserved. Case-sensitive.

namestring required
descriptionstring nullable
status'draft' | 'published' required
scopePathstring required

Tenant scope for delegated agent access: zero or more segments, each 1–128 chars from the external-id charset and each ending in /, e.g. acct_9f3/entity_dubai/. Empty means unscoped — invisible to every delegated grant.

createdAtstring required

UTC, ISO 8601 without a timezone suffix.

updatedAtstring required

UTC, ISO 8601 without a timezone suffix.

schemaobject nullable

JSON Schema of the render data payload.

schemaLockedboolean required

When true the data contract is frozen: embedded editing can restyle the document but cannot add, remove or retype a field.

sampleDataobject nullable

Example data satisfying schema.

baseTemplateIdstring nullable

Internal id of the base template this one layers on, if any.

versioninteger nullable

Present when version was given: the frozen version schema and sampleData come from, or null for the working copy.

channelstring nullable

Present when version was given: the channel the selector resolved through, if any.

Example response

{
  "scopePath": "acct_9f3/entity_dubai/",
  "createdAt": "2026-08-30T12:00:00.123456",
  "updatedAt": "2026-08-30T12:00:00.123456"
}

Changes

No recorded changes to this operation across all 1 revision of this API.