v1
ApplicationAPI & CLI
Northflank docs for LLMs
API
CLI
JS Client

Project / Volumes /

Create volume

Creates a volume with the specified payload

Required permission

Project > Volumes > General > Create

Path parameters

    • projectId

      string required
      ID of the project

Request body

  • {object}

    • name

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

    • stageId

      string
      min length
      3
      max length
      100
      pattern
      ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

    • tags

      [array]
      An array of previously defined tags to help identify and group the resource.
      • string
        min length
        3
        max length
        100
        pattern
        ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

    • mounts

      [array] required
      Array of mounts, containerMountPaths must be unique
      • {object}

        • volumeMountPath

          string
          Optionally specify the path inside this volume that should be mounted
          pattern
          ^((?!\.\.).)*$

        • containerMountPath

          string required
          Specify the path into which the volume should be mounted
          pattern
          ^((?!:).)*$

    • spec

      {object} required
      Example storage schema

    • source

      {object}

      • type

        string required
        one of
        volume, backup

      • sourceId

        string required
        Reference to the source object. For a volume source: "<volumeId>". For a backup source, prefer the backup UUID. Legacy "<volumeId>/<backupId>" and "<projectId>/<volumeId>/<backupId>" references remain supported.

    • owningObject

      {object}
      DEPRECATED: The object to attach this volume to.

      • id

        string required
        The id of object to attach this volume to.
        pattern
        ^[A-Za-z0-9-]+$

      • type

        string required
        The type of the object to attach this volume to.
        one of
        service, job

    • attachedObjects

      [array]
      Array of objects this volume is attached to.
      • {object}
        The object to attach this volume to.

        • id

          string required
          The id of object to attach this volume to.
          pattern
          ^[A-Za-z0-9-]+$

        • type

          string required
          The type of the object to attach this volume to.
          one of
          service, job

    • backupSchedules

      [array]
      Backup schedules for the volume. Snapshot-only.
      • {object}

        • scheduling

          {object} required
          Schedule for the backup.

          • interval

            string required
            The interval between backups. Each addon can only have one backup schedule of each interval for each backup type.
            one of
            hourly, daily, weekly

          • minute

            [array] required
            An array of minutes when the backup should be performed.
            • integer
              A minute when the backup should be performed.
              min
              0
              max
              59

          • hour

            [array]
            An array of hours in 24 hour format when the backup should be performed. At these hours, a backup will be performed at each of the minutes provided in the `minute` field. Required for `daily` and `weekly` intervals and unavailable for `hourly` intervals.
            • integer
              An hour when the backup should be performed, in 24 hour format.
              min
              0
              max
              23

          • day

            [array]
            An array of days of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday. On these days, a backup will be performed at each of the minutes provided in the `minute` field whenever it is an hour from the `hour` field. Required for `weekly` intervals and unavailable for `hourly` and `daily` intervals.
            • integer
              A day of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday.
              min
              0
              max
              6

        • retentionTime

          integer required
          The time the backup is retained for, in days.
          min
          1

Response body

  • {object}
    Response object.

    • data

      {object} required
      Result data.

      • id

        string required
        Identifier for the volume

      • name

        string required
        Volume name

      • tags

        [array] required
        An array of previously defined tags to help identify and group the resource.
        • string
          min length
          3
          max length
          100
          pattern
          ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$

      • spec

        {object} required
        Example storage schema

      • attachedObjects

        [array]
        List of objects this volume is attached to.
        • {object}
          The object to attach this volume to.

          • id

            string required
            The id of object to attach this volume to.
            pattern
            ^[A-Za-z0-9-]+$

          • type

            string required
            The type of the object to attach this volume to.
            one of
            service, job

      • backupSchedules

        [array]
        • {object}

          • scheduling

            {object} required
            Schedule for the backup.

            • interval

              string required
              The interval between backups. Each addon can only have one backup schedule of each interval for each backup type.
              one of
              hourly, daily, weekly

            • minute

              [array] required
              An array of minutes when the backup should be performed.
              • integer
                A minute when the backup should be performed.
                min
                0
                max
                59

            • hour

              [array]
              An array of hours in 24 hour format when the backup should be performed. At these hours, a backup will be performed at each of the minutes provided in the `minute` field. Required for `daily` and `weekly` intervals and unavailable for `hourly` intervals.
              • integer
                An hour when the backup should be performed, in 24 hour format.
                min
                0
                max
                23

            • day

              [array]
              An array of days of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday. On these days, a backup will be performed at each of the minutes provided in the `minute` field whenever it is an hour from the `hour` field. Required for `weekly` intervals and unavailable for `hourly` and `daily` intervals.
              • integer
                A day of the week when the backup should be performed, where `0` represents Monday and `6` represents Sunday.
                min
                0
                max
                6

          • retentionTime

            integer required
            The time the backup is retained for, in days.
            min
            1

      • status

        string required
        Status the volume is in on the cluster

      • createdAt

        string required
        The timestamp the volume was created at

      • updatedAt

        string required
        The timestamp the volume was last updated at
API
CLI
JS Client

POST /v1/projects/{projectId}/volumes

POST /v1/teams/{teamId}/projects/{projectId}/volumes

Example request

Request body
curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Volume","mounts":[{"volumeMountPath":"","containerMountPath":"/container"}],"spec":{"storageClassName":"nvme","storageSize":6144,"accessMode":"ReadWriteOnce"},"source":{"sourceId":"6d542e24-5d9f-4ecf-80a5-e80724b9133e","type":"volume"},"attachedObjects":[{"id":"example-service","type":"service"}],"backupSchedules":[{"scheduling":{"interval":"weekly","minute":[30],"hour":[18],"day":[4]},"retentionTime":7}]}' \
  https://api.northflank.com/v1/projects/{projectId}/volumes

Example response

200 OK

Details about the newly created volume.

JSON

{
  "data": {
    "id": "example-volume",
    "name": "Example Volume",
    "spec": {
      "storageClassName": "nvme",
      "storageSize": 6144
    },
    "attachedObjects": [
      {
        "id": "example-service",
        "type": "service"
      }
    ],
    "backupSchedules": [
      {
        "scheduling": {
          "interval": "weekly",
          "minute": [
            30
          ],
          "hour": [
            18
          ],
          "day": [
            4
          ]
        },
        "retentionTime": 7
      }
    ],
    "status": "BOUND",
    "createdAt": "2021-01-01 12:00:00.000Z",
    "updatedAt": "2021-01-01 12:00:00.000Z"
  }
}

Example response

409 Conflict

There is already a volume with the same derived identifier

© 2026 Northflank Ltd. All rights reserved.

northflank.com / Terms / Privacy / feedback@northflank.com