v1
ApplicationAPI & CLI
Double column
API
CLI
JS Client

Preview Blueprints /

Run preview blueprint

Runs a given preview blueprint with given arguments. This endpoint can be used as part of a CI pipeline to automatically create a preview environment.

Required permission

Project > PreviewBlueprints > Runs > Start

Path parameters

    • projectId

      string required
      ID of the project

    • previewBlueprintId

      string required
      ID of the preview blueprint

Request body

  • {object}

    • name

      string
      The optional name of the preview blueprint run.
      min length
      3
      max length
      39
      pattern
      ^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$

    • description

      string
      The optional description of the preview blueprint run.
      max length
      200
      pattern
      ^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$

    • arguments

      {object}
      A set of arguments that can be referenced in a template using '${args.argumentName}'.

      • triggers

        {object}
        Values passed in as blueprint triggers. This should be an object where each key corresponds to a trigger ref in the template. The values of each of these keys should also be an object, where each key value pair provided will set the value for that key in the given trigger. For example, the value `{ 'example-trigger': { 'branch': 'devel' } }` would set the `branch` field to `devel` for the trigger with ref `example-trigger`.
      API
      CLI
      JS Client

      POST /v1/projects/{projectId}/preview-blueprints/{previewBlueprintId}/runs

      Example request

      Request body
      curl
      curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Run","description":"This is a description for the preview blueprint run.","arguments":{"ARG_1":"value"},"triggers":{"example-trigger":{"branch":"devel"}}}' \
  https://api.northflank.com/v1/projects/{projectId}/preview-blueprints/{previewBlueprintId}/runs

      Example response

      200 OK

      success

      © 2026 Northflank Ltd. All rights reserved.

      northflank.comTermsPrivacyfeedback@northflank.com