AssetResp

Full asset — returned by GET /assets/{key}, POST /assets, PUT .../versions/draft, and POST .../versions/draft/publish. Carries the asset'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.

Note: for binary asset types, the response carries the fileId reference; download the binary separately via the file endpoint.

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 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/initiate-upload 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
  
  Reference to an uploaded binary file. Required for pdf and image asset types. Upload via POST .../files/initiate-upload to obtain this ID.
- 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.
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 asset 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