Templates /

Create template

Create a template

Required permission

Account > Templates > General > Create

Request body

{object}
Create a new template

name
string required
Name of the template.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[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
project
(multiple options: oneOf) required
Details of the project the template will run in.

{object}

Use an existing project

id
string required
The ID of the project to use.
pattern
^[A-Za-z0-9-]+$

{object}

Create a new project

spec
(multiple options: oneOf) required

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

spec
(multiple options: oneOf) required
A node representing an action to be performed as part of the template.
concurrencyPolicy
string
Defines the concurrency behaviour of the template with respect to parallel runs.
one of
allow, queue, forbid
argumentOverrides
{object}
Argument overrides stored outside of the template. If GitOps is enabled, these will not be saved in version control.

options
{object}
Additional options for the template creation.

runOnCreation
boolean
If true, the template will be ran immediately after creation.
runOnCreationArgumentOverrides
{object}
Argument overrides for the initial run. Valid only if runOnCreation is true.

autorun
boolean
If true, the template will run automatically whenever it is updated.

{object}
Create a new template with GitOps enabled (push to git)

name
string required
Name of the template.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[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
project
(multiple options: oneOf) required
Details of the project the template will run in.

{object}

Use an existing project

id
string required
The ID of the project to use.
pattern
^[A-Za-z0-9-]+$

{object}

Create a new project

spec
(multiple options: oneOf) required

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

spec
(multiple options: oneOf) required
A node representing an action to be performed as part of the template.
concurrencyPolicy
string
Defines the concurrency behaviour of the template with respect to parallel runs.
one of
allow, queue, forbid
argumentOverrides
{object}
Argument overrides stored outside of the template. If GitOps is enabled, these will not be saved in version control.

options
{object}
Additional options for the template creation.

runOnCreation
boolean
If true, the template will be ran immediately after creation.
runOnCreationArgumentOverrides
{object}
Argument overrides for the initial run. Valid only if runOnCreation is true.

autorun
boolean
If true, the template will run automatically whenever it is updated.

gitops
{object} required
GitOps data for syncing this template with a file in version control.

vcsService
string required
The VCS provider to use.
one of
bitbucket, gitlab, github, self-hosted
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-]+$
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.
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-._]+$

{object}
Create a new template with GitOps enabled (use an existing git template)

name
string required
Name of the template.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
Description of the template.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
concurrencyPolicy
string
Defines the concurrency behaviour of the template with respect to parallel runs.
one of
allow, queue, forbid
argumentOverrides
{object}
Argument overrides stored outside of the template. If GitOps is enabled, these will not be saved in version control.

options
{object}
Additional options for the template creation.

runOnCreation
boolean
If true, the template will be ran immediately after creation.
runOnCreationArgumentOverrides
{object}
Argument overrides for the initial run. Valid only if runOnCreation is true.

autorun
boolean
If true, the template will run automatically whenever it is updated.

gitops
{object} required
GitOps data for syncing this template with a file in version control.

vcsService
string required
The VCS provider to use.
one of
bitbucket, gitlab, github, self-hosted
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-]+$
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.
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-._]+$

Response body

{object}
Response object.

data
{object} required
Result data.

template
{object} required
Details about the newly created template.

name
string required
Name of the template.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[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
project
(multiple options: oneOf) required
Details of the project the template will run in.

{object}

Use an existing project

id
string required
The ID of the project to use.
pattern
^[A-Za-z0-9-]+$

{object}

Create a new project

spec
(multiple options: oneOf) required

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

spec
(multiple options: oneOf) required
A node representing an action to be performed as part of the template.
id
string required
Identifier for the template
gitops
{object}

vcsService
string required
The VCS provider to use.
one of
bitbucket, gitlab, github, self-hosted
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-]+$
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.
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-._]+$
templateSha
string required
The SHA of the current commit that is being used for the template.

concurrencyPolicy
string
Defines the concurrency behaviour of the template with respect to parallel runs.
one of
allow, queue, forbid
options
{object} required

autorun
boolean required
Whether autorun is enabled

createdAt
string
time of creation
updatedAt
string
time of update

templateRun
{object}

name
string required
Name of the template.
min length
3
max length
39
pattern
^[a-zA-Z]((-|\s)?[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
project
(multiple options: oneOf) required
Details of the project the template will run in.

{object}

Use an existing project

id
string required
The ID of the project to use.
pattern
^[A-Za-z0-9-]+$

{object}

Create a new project

spec
(multiple options: oneOf) required

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

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

Example request

Request body

Create a new template

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Template","description":"This is a sample template.","apiVersion":"v1","arguments":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"spec":{"kind":"Workflow","spec":{"type":"sequential","steps":[null]}},"concurrencyPolicy":"allow","argumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"options":{"runOnCreation":true,"runOnCreationArgumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"autorun":false}}' \
  https://api.northflank.com/v1/templates

Create a new template with GitOps enabled (push to git)

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Template","description":"This is a sample template.","apiVersion":"v1","arguments":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"spec":{"kind":"Workflow","spec":{"type":"sequential","steps":[null]}},"concurrencyPolicy":"allow","argumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"options":{"runOnCreation":true,"runOnCreationArgumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"autorun":false},"gitops":{"vcsService":"github","accountLogin":"github-user","repoUrl":"https://github.com/northflank-examples/remix-postgres-redis-demo","branch":"main","filePath":"northflank.json"}}' \
  https://api.northflank.com/v1/templates

Create a new template with GitOps enabled (use an existing git template)

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Template","description":"This is a sample template.","concurrencyPolicy":"allow","argumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"options":{"runOnCreation":true,"runOnCreationArgumentOverrides":{"ARGUMENT_1":"value_1","ARGUMENT_2":"value_2"},"autorun":false},"gitops":{"vcsService":"github","accountLogin":"github-user","repoUrl":"https://github.com/northflank-examples/remix-postgres-redis-demo","branch":"main","filePath":"northflank.json"}}' \
  https://api.northflank.com/v1/templates

Example response

200 OK

Details about the newly created template.

JSON

{
  "data": {
    "template": {
      "name": "Example Template",
      "description": "This is a sample template.",
      "apiVersion": "v1",
      "arguments": {
        "ARGUMENT_1": "value_1",
        "ARGUMENT_2": "value_2"
      },
      "spec": {
        "kind": "Workflow",
        "spec": {
          "type": "sequential",
          "steps": [
            null
          ]
        }
      },
      "id": "example-template",
      "gitops": {
        "vcsService": "github",
        "accountLogin": "github-user",
        "repoUrl": "https://github.com/northflank-examples/remix-postgres-redis-demo",
        "branch": "main",
        "filePath": "northflank.json",
        "templateSha": "8c7e040ee3737ddc3a713363ae72bbe960e9fb16"
      },
      "concurrencyPolicy": "allow"
    },
    "templateRun": {
      "name": "Example Template",
      "description": "This is a sample template.",
      "apiVersion": "v1",
      "arguments": {
        "ARGUMENT_1": "value_1",
        "ARGUMENT_2": "value_2"
      },
      "spec": {
        "settings": {
          "maxAttempts": 3,
          "backoff": {
            "type": "fixed",
            "delay": 60
          }
        },
        "kind": "Workflow",
        "response": {
          "status": "success",
          "retries": {
            "attempts": 1,
            "maxAttempts": 3,
            "timestamp": 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"
    }
  }
}