TemplateResp

Full template — returned by GET /templates/{key}, POST /templates, PUT .../versions/draft, and POST .../versions/draft/publish. Carries the template's identity (metadata), content (spec), and audit/publish metadata.

The optimistic-locking handle is returned in the HTTP ETag response header (RFC 7232) — capture it from the response and pass it back as If-Match on the next PUT / DELETE.

  • contentHash
    Type: string
    required

    Stable hash of the resource's content. Recomputed on every write (Create, Update, Publish), so it's available for both drafts and published versions. Useful for change detection — compare hashes across two snapshots (e.g. "did the draft actually change?" or "is the draft different from the latest published version?").

  • createdAt
    Type: stringFormat: date-time
    required

    When this version was created.

  • createdBy
    Type: object
    required

    Actor who created this version.

    • id
      Type: string
      required

      Stable ID for the actor (UUID for users; the API key's keyId for service accounts).

    • type
      Type: stringenum
      required
      values
      • user
      • api_key
  • metadata
    Type: object
    required

    The resource's identity and human-facing labels. Shared shape across all five resource kinds (blueprints, templates, schemas, assets, functions). The pair (key, version) is the canonical handle for any resource within a namespace.

    • key
      Type: string Pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
      required

      Caller-supplied identifier, unique within the namespace per kind. Stable across versions — a blueprint's key doesn't change when you publish a new version. Snake_case; must start with a lowercase letter.

    • name
      Type: string
      max length:  
      200
      required

      Human-readable display name shown in Studio, list responses, and audit trails (max 200 chars).

    • version
      Type: string
      required

      Either draft (editable; only one draft per key at a time) or a semver like 1.2.0 (immutable once published). On create you choose: pass draft to iterate, or a semver to publish directly.

    • description
      Type: string
      max length:  
      1000

      Optional longer-form description. Helps both humans and AI assistants pick the right resource when browsing the catalog (max 1000 chars).

    • labels
      Type: object

      Arbitrary key/value tags for categorization and filtering — e.g. { "team": "people-ops", "env": "prod" }. Filterable on list endpoints via ?labels[key]=value.

  • spec
    Type: object
    required

    The template's content. type is required — pdf or html — and determines the rendering pipeline:

    • pdf — overlays declared fields (signature placements, text fields, checkboxes, etc.) onto the underlying PDF asset (contentKey + contentVersion). Field values come from JSONata expressions evaluated against the supplied inputs.
    • html — the underlying HTML asset is a Handlebars template. The supplied inputs first run through the JSONata expression in spec.data.transform to produce a viewModel — the data context Handlebars renders against. The compiled HTML is then converted to a PDF.

    The remaining fields configure which entity inputs the template needs (inputs), what signing roles it exposes (roles), and which JSONata functions it can call (functions). Templates are the building blocks of blueprint envelopes.

    • type
      Type: stringenum
      required

      Template kind. pdf overlays fields on a PDF asset; html renders an HTML template (with an optional data transform).

      values
      • pdf
      • html
    • contentKey
      Type: string

      Asset key for the underlying PDF or HTML content. Pair with contentVersion.

    • contentVersion
      Type: string

      Specific version of the content asset to use.

    • data
      Type: object

      HTML-only. Configures the input → viewModel transform. The transform JSONata expression reshapes raw entity inputs into the data context the underlying Handlebars template renders against. See HtmlDataConfig.

    • fields
      Type: array object[] · TemplateFieldInfo[]

      Field placements on the rendered output (signature, text, checkbox, image, etc.). Each field declares its position, dimensions, optional default value (literal or expression), and optional role assignment.

    • functions
      Type: array object[]

      JSONata functions referenced by expressions inside this template. Each entry pins a specific function key + version, with an optional alias used at call sites.

    • inputs
      Type: array object[] · Input[]

      Entity inputs the caller (or parent blueprint) must supply when rendering this template.

    • roles
      Type: array object[] · TemplateRole[]

      Signing roles declared by this template. Blueprint participants get assigned to these roles via document assignments at the orchestration step level.

  • updatedAt
    Type: stringFormat: date-time
    required

    When this version was last modified (drafts only — published versions are immutable).

  • apiVersion
    Type: string

    API version of the resource shape this template was stored against.

  • publishedAt
    Type: stringFormat: date-time

    When this version was published. Absent on drafts.

  • publishedBy
    Type: object

    Actor who published this version. Absent on drafts.

    • id
      Type: string
      required

      Stable ID for the actor (UUID for users; the API key's keyId for service accounts).

    • type
      Type: stringenum
      required
      values
      • user
      • api_key