Ciresk Docs
API reference

Templates

Publish a template as an organization version, list versions and promote one for a repository pattern.

GET/v1/dev/templates

List template versions

The organisation's template versions, newest first, each with the repository patterns it is active for.

Permission: dev:templates.read

Parameters

NameTypeRequiredDescription
cursorquerystringOptional
limitqueryintegerOptional
templatequerystringOptional

Response200 OK

dataarray of objectsRequired
data[].active_forarray of stringsRequired
the patterns this version is active for: * or repositories
data[].idstringRequired
devtv_<uuidv7> behind the cell that minted it
data[].imagesarray of stringsRequired
the template's pinned images
data[].parametersarray of objects
the template's parameters in its order; empty for a version published before dev-api kept them
data[].parameters[].defaultstringRequired
data[].parameters[].descriptionstring
data[].parameters[].maxinteger or null
number only
data[].parameters[].mininteger or null
number only
data[].parameters[].mutablebooleanRequired
true: a person's dev up with another value recreates the session; false: only dev up --recreate takes another value
data[].parameters[].namestringRequired
data[].parameters[].optionsarray of strings
choice only
data[].parameters[].typestringRequired
string: at most 256 characters, no control character; number: a whole number within min and max; bool: true or false; choice: one of optionsOne of string, number, bool, choice
data[].presetsarray of objects
data[].presets[].descriptionstring
data[].presets[].namestringRequired
data[].presets[].valuesmap of stringRequired
data[].published_atstring (date-time)Required
data[].published_bystringRequired
data[].templatestringRequired
data[].template_digeststringRequired
has_morebooleanRequired
next_cursorstring or null

Errors

  • 401an error
  • 403an error
  • 422validation_failed (a template name off its pattern)
curl "$CIRESK_API/v1/dev/templates" \
  -H "Authorization: Bearer $CIRESK_KEY"
POST/v1/dev/templates

Publish a template version

Publish one template of a dev file as an organisation template version.

Stores the template's name, the dev file's digest and the template's pinned images as an immutable version of the organisation. The file is parsed and the named template validated first (422 template_invalid with the findings). Publishing a name and digest already published answers that version with 200.

Permission: dev:templates.write

Request body

templatestringRequired
template_b64stringRequired
the dev file's bytes
template_digeststringRequired

Response200 OK

active_forarray of stringsRequired
the patterns this version is active for: * or repositories
idstringRequired
devtv_<uuidv7> behind the cell that minted it
imagesarray of stringsRequired
the template's pinned images
parametersarray of objects
the template's parameters in its order; empty for a version published before dev-api kept them
parameters[].defaultstringRequired
parameters[].descriptionstring
parameters[].maxinteger or null
number only
parameters[].mininteger or null
number only
parameters[].mutablebooleanRequired
true: a person's dev up with another value recreates the session; false: only dev up --recreate takes another value
parameters[].namestringRequired
parameters[].optionsarray of strings
choice only
parameters[].typestringRequired
string: at most 256 characters, no control character; number: a whole number within min and max; bool: true or false; choice: one of optionsOne of string, number, bool, choice
presetsarray of objects
presets[].descriptionstring
presets[].namestringRequired
presets[].valuesmap of stringRequired
published_atstring (date-time)Required
published_bystringRequired
templatestringRequired
template_digeststringRequired

Errors

  • 401an error
  • 403an error
  • 422validation_failed (a template name off its pattern, a dev file over 256 KiB or not base64), template_invalid (members findings; a template_digest that is not the digest of template_b64)
curl -X POST "$CIRESK_API/v1/dev/templates" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "platform",
    "template_b64": "dmVyc2lvbjogMQp0ZW1wbGF0ZXM6CiAgcGxhdGZvcm06IHt9Cg==",
    "template_digest": "sha256:594a7fce866c492eace239ff639d9cc6cec7df777c152af6729dbae01dba6e91"
  }'
POST/v1/dev/templates/{version_id}/promote

Promote a template version

Make a version the active one of its template for a repository pattern.

One active version per (pattern, template name): a promotion replaces the earlier one and its record holds both. The pattern is * (every repository) or one repository, as a remote url or normalised (github.com/acme/app); the repository's own promotion wins over *. Under the policy's templates: published, dev up admits only the active version.

Permission: dev:templates.write

Parameters

NameTypeRequiredDescription
version_idpathstringRequiredThe version's ID.

Request body

repositorystringRequired
* or one repository: a remote url or its normalised form (github.com/acme/app)

Response200 OK

promoted_atstring (date-time)Required
promoted_bystringRequired
replacedstring or null
the version that was active for this pattern before
repositorystringRequired
* or the normalised repository
templatestringRequired
version_idstringRequired

Errors

  • 401an error
  • 403an error
  • 404template_version_not_found
  • 422validation_failed (a version id off devtv_<32 hex>, a repository that is neither * nor one repository)
curl -X POST "$CIRESK_API/v1/dev/templates/6bef13d5-0ba2-41c4-9426-a06a581b7d2c/promote" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/platform"
  }'