BlueprintsUsers

Publish templates with the API

Validate a blueprint template, save it to your boundary's catalog, replace it and delete it through the platform API.

Requires: blueprints/templates/write

The templates API saves one template at a time to a boundary's catalog. The portal has no screen for it; call it with stsh api or any HTTP client, as described in Platform API. Every route here needs blueprints/templates/write on the boundary.

Prepare the request body

Each request carries the template, YAML or JSON, as a string in content:

json

{ "content": "apiVersion: blueprints.stackship.se/v2\nkind: BlueprintTemplate\n..." }

With jq, from a template.yaml:

bash

jq -Rs '{content: .}' template.yaml > body.json

Validate a template

bash

stsh api POST /boundaries/<boundary-id>/resources/blueprints/templates/validate -d @body.json

Validation checks the document without storing it. A valid template answers 200 with {"valid": true}; an invalid one answers 400 with every problem and where it is:

json

{
  "valid": false,
  "errors": [
    { "path": "metadata.title", "message": "A title is required" },
    { "path": "instance.components", "message": "A template must declare at least one component" }
  ]
}

Validate templates you keep in a repository too: a catalog source skips a template that does not parse without saying so.

Save or replace a template

bash

stsh api POST /boundaries/<boundary-id>/resources/blueprints/templates -d @body.json

The template is validated again and saved under its metadata.slug; the answer is 204, or 400 with errors as above. Saving a slug that already exists in the boundary replaces that blueprint. A slug the platform catalog uses is refused. A blueprint that a catalog source publishes is replaced only until that source's next sync, which writes the repository's version back.

The blueprint appears in the boundary's catalog at once. Templates saved this way are stored exactly as sent: {{domain_suffix}} and {{cert_issuer}} are not replaced, and hidden is not applied — see Metadata.

Read a template

The catalog routes return any blueprint visible in the boundary, including the ones you saved:

bash

stsh api GET /boundaries/<boundary-id>/resources/blueprints/<slug>

The answer describes the blueprint as the catalog shows it — its parameters, components and managed resources — not the template document itself. Keep the document where you edit it.

Delete a template

bash

stsh api DELETE /boundaries/<boundary-id>/resources/blueprints/templates/<slug>

The answer is 204, or 404 when the boundary has no blueprint with that slug; the platform catalog's blueprints cannot be deleted here. A blueprint that a catalog source publishes can be, but comes back at that source's next sync. Instances already deployed from the template keep running.