v1
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
                    min
                    1024
                • shmSize

                  integer
                  Configures the amount of available memory-backed disk space available to /dev/shm
                  min
                  64
              • 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
                    min
                    1024
                • shmSize

                  integer
                  Configures the amount of available memory-backed disk space available to /dev/shm
                  min
                  64
              • 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.