CreateBlueprintReq

Request body for creating a blueprint. Carries the blueprint's identity (metadata) and content (spec).

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

  • apiVersion
    Type: string

    Optional API version of the resource shape. Defaults to the current spec version.