v1
ApplicationAPI & CLI
Double column
API
CLI
JS Client

Jobs /

Run job

Starts a new job run for the given job

Required permission

Project > Jobs > General > Read

Path parameters

    • projectId

      string required
      ID of the project

    • jobId

      string required
      ID of the job

Request body

  • {object}

    • runtimeEnvironment

      {object}
      An object containing the environment variables overrides to use when running the job. Keys may only contain letters, numbers, hyphens, forward slashes and dots.

      • runtimeFiles

        {object}
        Secret files as JSON object, encrypted at rest. File path must be absolute

        • dockerSecretMounts

          {object}
          Docker secret mount contents as JSON object, encrypted at rest. Must be a valid Docker secret mount identifier

          • billing

            {object}

            • deploymentPlan

              string
              The ID of the deployment plan override to use.
              min length
              3
              max length
              100
              pattern
              ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

          • deployment

            (multiple options: oneOf)
            Override the job run deployment source.
            • {object}
              Optional: Override the run to use a previously built commit

              • docker

                {object}
                Allows for customization of docker runtime

                • configType

                  string required
                  Type of entrypoint & command override configuration
                  one of
                  default, customEntrypoint, customCommand, customEntrypointCustomCommand

                • customEntrypoint

                  string
                  Custom entrypoint which should be used. Required in case where `configType` is `customEntrypoint` or `customEntrypointCustomCommand`

                • customCommand

                  string
                  Custom command which should be used. Required in case where `configType` is `customCommand` or `customEntrypointCustomCommand`

              • buildpack

                {object}
                Allows for customization of buildpack runtime

                • configType

                  string required
                  Type of buildpack run configuration
                  one of
                  default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand

                • customProcess

                  string
                  Custom process which should be run. Required in case where `configType` is `customProcess`

                • customEntrypoint

                  string
                  Custom entrypoint which should be run. Required in case where `configType` is `customEntrypointCustomCommand`

                • customCommand

                  string
                  Custom command which should be run. Required in case where `configType` is `customCommand`, `customEntrypointCustomCommand` or `originalEntrypointCustomCommand`

              • storage

                {object}

                • ephemeralStorage

                  {object}

                  • storageSize

                    integer
                    Ephemeral storage per container in MB
                    one of
                    1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800, 256000, 307200, 409600, 512000
                    min
                    1024
                    max
                    204800

                • shmSize

                  integer
                  Configures the amount of available memory-backed disk space available to /dev/shm
                  one of
                  64, 128, 256, 512, 1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 143360
                  min
                  64
                  max
                  61440

              • internal

                {object}
                Optional: Specify the commit to run

                • id

                  string
                  ID of the build service to deploy
                  min length
                  3
                  max length
                  54
                  pattern
                  ^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

                • branch

                  string
                  Branch to deploy

                • buildSHA

                  (multiple options: oneOf)
                  Commit SHA to deploy, or 'latest' to deploy the most recent commit
                  • string
                    A commit sha.
                    min length
                    40
                    max length
                    40

                    • OR

                  • string
                    Latest commit.
                    one of
                    latest

                • buildId

                  string
                  ID of the build that should be deployed

              OR

            • {object}
              Optional: Override the run to use an external image

              • docker

                {object}
                Allows for customization of docker runtime

                • configType

                  string required
                  Type of entrypoint & command override configuration
                  one of
                  default, customEntrypoint, customCommand, customEntrypointCustomCommand

                • customEntrypoint

                  string
                  Custom entrypoint which should be used. Required in case where `configType` is `customEntrypoint` or `customEntrypointCustomCommand`

                • customCommand

                  string
                  Custom command which should be used. Required in case where `configType` is `customCommand` or `customEntrypointCustomCommand`

              • buildpack

                {object}
                Allows for customization of buildpack runtime

                • configType

                  string required
                  Type of buildpack run configuration
                  one of
                  default, customProcess, customCommand, customEntrypointCustomCommand, originalEntrypointCustomCommand

                • customProcess

                  string
                  Custom process which should be run. Required in case where `configType` is `customProcess`

                • customEntrypoint

                  string
                  Custom entrypoint which should be run. Required in case where `configType` is `customEntrypointCustomCommand`

                • customCommand

                  string
                  Custom command which should be run. Required in case where `configType` is `customCommand`, `customEntrypointCustomCommand` or `originalEntrypointCustomCommand`

              • storage

                {object}

                • ephemeralStorage

                  {object}

                  • storageSize

                    integer
                    Ephemeral storage per container in MB
                    one of
                    1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 153600, 204800, 256000, 307200, 409600, 512000
                    min
                    1024
                    max
                    204800

                • shmSize

                  integer
                  Configures the amount of available memory-backed disk space available to /dev/shm
                  one of
                  64, 128, 256, 512, 1024, 2048, 5120, 10240, 20480, 30720, 40960, 51200, 61440, 81920, 102400, 122880, 143360
                  min
                  64
                  max
                  61440

              • external

                {object}
                Optional: Specify the external image to run

                • imagePath

                  string required
                  Image to be deployed. When not deploying from Dockerhub the URL must be specified.
                  pattern
                  ^(?:(?:https?:\/\/)?([a-zA-Z0-9\-]+\.[a-zA-Z0-9\.\-]+)(\/v1)?)?(?:\/)?([a-zA-Z/-9\.\-_]+)(?:\:([a-zA-Z/-9\.\-_\:]+)|\@([a-zA-Z/-9\.\-_\:]+))$

                • credentials

                  string
                  ID of the saved credentials to use to access this external image.
                  pattern
                  ^[A-Za-z0-9-]+$

        Response body

        • {object}
          Response object.

          • data

            {object} required
            Result data.

            • id

              string required
              The ID of the job run

            • runName

              string required
              The name of the job run
        API
        CLI
        JS Client

        POST /v1/projects/{projectId}/jobs/{jobId}/runs

        Example request

        Request body
        curl
        curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"runtimeEnvironment":{"VARIABLE_1":"abcdef","VARIABLE_2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"dockerSecretMounts":{"example-secret-mount_1":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"billing":{"deploymentPlan":"nf-compute-20"},"deployment":{"docker":{"configType":"default"},"storage":{"ephemeralStorage":{"storageSize":1024}},"internal":{"id":"example-build-service","branch":"master","buildId":"premium-guide-6393"}}}' \
  https://api.northflank.com/v1/projects/{projectId}/jobs/{jobId}/runs

        Example response

        200 OK

        Details about the new job run.

        JSON

        {
  "data": {
    "id": "d34582a4-35bd-4c71-8e7c-e36999b88723",
    "runName": "example-job-5fcf67bc56e1913e21d49504"
  }
}

        © 2025 Northflank Ltd. All rights reserved.

        northflank.comTermsPrivacyfeedback@northflank.com