v1
ApplicationAPI & CLI
Double column
API
CLI
JS Client

Templates /

Run template

Run a template

Required permission

Account > Templates > General > Run

Path parameters

    • templateId

      string required
      ID of the template

Request body

  • {object}

    • arguments

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

    Response body

    • {object}
      Response object.

      • data

        {object} required
        Result data.

        • name

          string required
          Name of the template.
          min length
          3
          max length
          100
          pattern
          ^[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*$

        • description

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

        • apiVersion

          string required
          The version of the Northflank API to run the template against.
          one of
          v1.2

        • options

          {object}
          Options regarding how the template is run.

          • autorun

            boolean
            If true, the template will run automatically whenever a change is made to it.

          • concurrencyPolicy

            string
            Defines the concurrency behaviour of the template with respect to parallel runs.
            one of
            allow, queue, forbid

        • arguments

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

          • gitops

            {object}

            • vcsService

              string required
              The VCS provider to use.
              one of
              bitbucket, gitlab, github, self-hosted, azure

            • selfHostedVcsId

              string
              If projectType is self-hosted, the ID of the self-hosted vcs to use.
              pattern
              ^([A-Za-z0-9-]+\/[A-Za-z0-9-]+)|([0-9a-f]{24})$

            • accountLogin

              string
              By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If `accountLogin` is provided, Northflank will instead use your linked account with that login name.

            • vcsLinkId

              string
              Legacy key. Please used accountLogin instead.

            • repoUrl

              string required
              URL of the Git repo to sync the template with.
              pattern
              ^(https:\/\/)?((www(\.[a-zA-Z0-9\-]{2,})+\.)?[a-zA-Z0-9\-]{2,})(\.([a-zA-Z0-9\-]{2,}))+(\/([a-zA-Z0-9\-._]{2,}))+?$

            • branch

              string required
              The name of the branch to use.

            • filePath

              string required
              The file path to the template in the repository. If using an existing template, it should be in JSON format.
              pattern
              ^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$

          • $schema

            string

          • spec

            (multiple options: oneOf) required
            A node representing an action to be performed as part of the template.

          • refs

            {object}

            • id

              string required
              Identifier for the template run

            • templateId

              string required
              Identifier for the template

            • status

              string required
              Status of the template run
              one of
              pending, running, success, failure, aborted, aborting, queued, unknown, skipped

            • concluded

              boolean required
              Whether the run has concluded (aborted, success, failed)

            • createdAt

              string required
              Timestamp the run was created at.

            • updatedAt

              string required
              Timestamp the run was last updated at.
        API
        CLI
        JS Client

        POST /v1/templates/{templateId}/runs

        Example request

        Request body
        curl
        curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data 'undefined' \
  https://api.northflank.com/v1/templates/{templateId}/runs

        Example response

        200 OK

        Details about the newly create template run.

        JSON

        {
  "data": {
    "name": "Example Template",
    "description": "This is a sample template.",
    "apiVersion": "v1.2",
    "options": {
      "autorun": false,
      "concurrencyPolicy": "allow"
    },
    "gitops": {
      "vcsService": "github",
      "accountLogin": "github-user",
      "repoUrl": "https://github.com/northflank-examples/remix-postgres-redis-demo",
      "branch": "main"
    },
    "spec": {
      "settings": {
        "maxAttempts": 3,
        "backoff": {
          "type": "fixed",
          "delay": 60
        }
      },
      "kind": "Workflow",
      "response": {
        "status": "success",
        "retries": {
          "attempts": 1,
          "maxAttempts": 3,
          "timestamp": 1657296265
        },
        "startTime": 1657296265,
        "endTime": 1657296265
      }
    },
    "id": "3dd592f6-ce63-45ee-acf8-13dc5ec5235c",
    "templateId": "example-template",
    "status": "success",
    "concluded": true,
    "createdAt": "2021-01-01 12:00:00.000Z",
    "updatedAt": "2021-01-01 12:00:00.000Z"
  }
}

        © 2025 Northflank Ltd. All rights reserved.

        northflank.comTermsPrivacyfeedback@northflank.com