BlueprintResp

Full blueprint — returned by GET /blueprints/{key}, POST /blueprints, PUT .../versions/draft, and POST .../versions/draft/publish. Carries the blueprint'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 blueprint's content. Only envelopes is required — at minimum a blueprint bundles documents to render. From there, optional fields layer on capability:

    • Add inputs to declare data the caller must supply when running the blueprint.
    • Add participants to declare the parties involved.
    • Add orchestration to drive those participants through a signing flow.

    Without orchestration, a blueprint is a document rendering engine — it generates documents from templates and (optionally) inputs, but doesn't trigger any signing. Add orchestration (typically with participants) to turn it into a full signing workflow.

    customFields and functions are auxiliary: customFields carry runtime metadata; functions pin JSONata functions referenced by expressions inside the blueprint.

    • envelopes
      Type: array object[] · BlueprintEnvelope[]
      required

      Required. Envelopes bundle documents that get rendered together (and, if orchestration is present, signed together).

      An envelope bundles documents that get rendered (and, if orchestration is present, signed) together. Multiple envelopes split a single blueprint into independent signing sessions — each envelope generates its own emails to participants and tracks its own completion state.

    • customFields
      Type: array object[] · CustomFieldConfig[]

      Custom fields whose values are computed at run time and carried alongside the blueprint output.

      Caller-extensible field carried alongside the blueprint at run time. Unlike inputs (data the caller supplies) or template fields (placed on documents), custom fields are arbitrary key/value metadata — useful for tagging workflows with reference IDs, deal numbers, or computed flags that downstream systems consume.

    • functions
      Type: array object[]

      JSONata functions referenced by expressions inside the blueprint. Each entry pins a specific function key + version, with an optional alias used at call sites (defaults to functionKey when not specified). Aliases let you decouple call-site names from resource keys so you can rename or swap functions without rewriting every expression.

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

      Optional. Entity inputs the caller must supply when running this blueprint. Omit if the blueprint's templates need no caller-supplied data.

    • orchestration
      Type: object

      Optional. Root step of the signing flow. Just two primitives:

      • participant — one task assigned to a participant. Set participantKey and action.
      • group — a container that runs children either sequentially or in parallel, with optional completion (all / any / quorum).

      Groups nest — that's the entire composition mechanism. From these two primitives plus nesting you can model any signing flow:

      • Linear chain — group:sequential of participants: A signs, then B, then C.
      • Parallel sign-off — group:parallel of participants: board members sign concurrently.
      • Phased approvals — group:sequential whose children are group:parallels: each phase opens after the previous one completes; signers within a phase work in parallel.
      • Quorum — group:parallel with completion: quorum, quorum: 2: first 2 of 3 approvers wins; the third is skipped.
      • Conditional branches — includeIf on any step gates the path on a JSONata expression evaluated at run time.

      onComplete on any step adds validation or entity-data updates when the step finishes — useful for chaining state forward (e.g. write the manager's signed-off salary into the next phase's inputs).

      Omit orchestration entirely to use the blueprint as a document rendering engine with no signing flow.

    • participants
      Type: array object[] · BlueprintParticipant[]

      Optional. Roles involved in the blueprint. Each participant's name/email may be bound dynamically from inputs via JSONata expressions. Omit for pure document-rendering blueprints (no signing).

      A party involved in the blueprint. key and name define the role slot ("Hiring Manager", "Candidate"); participantName and participantEmail resolve to the actual person at run time, either as literals or via JSONata expressions that derive them from inputs.

  • 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 blueprint 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