AssetSpec

The asset's content. type is required and determines the asset kind (PDF, HTML, image, CSS), which in turn determines whether the binary content is referenced via fileId or supplied inline as content.

  • Binary types (pdf, image) — upload the file first via POST .../files/upload-url and pass the returned ID in fileId.
  • Text types (html, css) — supply the content inline as a string in content.

HTML assets additionally use htmlConfig to declare partials, styles, images, the viewModel schema, and PDF rendering options. HTML assets are wrapped by HTML templates and rendered via Handlebars.

  • type
    Type: stringenum
    required

    Asset kind — determines whether the binary lives at fileId (binary) or inline at content (text).

    values
    • html
    • image
    • pdf
    • css
  • content
    Type: string

    Inline text content. Required for html and css asset types. Pass the raw HTML source or CSS rules as a string.

  • fileId
    Type: string Pattern: ^f_[0-9a-z]{26}$

    Reference to an uploaded binary file. Required for pdf and image asset types. Upload via POST .../files/upload-url to obtain this ID. Prefixed lowercase ULID, e.g. f_01jv8m7qfj6xj9gkz7a4s2h8e.

  • htmlConfig
    Type: object

    HTML-only. Declares assets the HTML template references (partials, styles, images), the viewModel schema, and PDF rendering options. Combined with the inline content (a Handlebars template), this configures how the HTML renders to PDF.

    • data
      Type: object

      Declares the schema the rendered viewModel (the JSON object passed to Handlebars as the root context) must conform to. Hosting templates validate the data they pass against this schema before rendering.

    • images
      Type: array object[]

      Image assets the template references. The renderer resolves each entry to a signed URL and exposes it via the {{asset_url 'alias'}} Handlebars helper — e.g., <img src="{{asset_url 'logo'}}">.

    • partials
      Type: array object[]

      Other HTML assets registered as Handlebars partials before rendering. Use {{> alias}} in content to inline a partial; nested partial references inside the included asset are resolved recursively.

      Data flow: a partial is just another HTML asset and carries its own data declaration (the viewModel shape it expects). Whatever data the partial actually receives must conform to that schema.

      Wiring happens at the call site in content using standard Handlebars syntax: {{> header}} invokes the partial against the caller's current context (which is the root viewModel by default — so the root viewModel itself must satisfy header's data schema). {{> header employee}} scopes the partial to employee; that scoped object then has to satisfy the schema. {{> header title="Welcome"}} passes hash arguments. It's on the parent template to make sure whatever it routes into a partial is the right shape — either by passing through the matching slice or by reshaping in its own viewModel transform.

      Use roleMap (below) to rewrite signing-role placeholders when reusing the same partial under different concrete roles.

    • pdfSettings
      Type: object

      PDF rendering options applied when the HTML is converted to PDF. Defaults to Letter if omitted.

    • styles
      Type: array object[]

      CSS assets inlined into a <style> block at render time, in the order listed. Cascade follows declaration order — later entries can override earlier ones. Only top-level styles are collected; styles declared on nested partials are ignored.