1.3. API Endpoint - Policies¶

A policy (specifically a policy-based tiering workflow) is an advanced data orchestration tool that automates the movement of data between storage pools or from pools to Ngenea targets. Policies are driven by conditions such as file age, size, access time, or storage pool utilization levels, enabling dynamic data management.

Difference from Workflow:

Policy: Operates vertically, automating data movement within storage tiers based on predefined conditions.
Workflow: Operates horizontally, focusing on moving data into or out of a site.

1.3.1. API Reference Location¶

All endpoints, parameters, and schemas can be explored through the interactive API documentation available at:

http(s)://<your-hub-address>/api/docs/

Note

Replace your-hub-address with the actual IP address or domain of your Ngenea Hub instance.

1.3.2. `GET` /policies/¶

Description

This endpoint allows you to retrieve a list of policies, with support for pagination. It returns a collection of policies configured in the system, including their details such as schedule, triggers, conditions, and other related configurations.

Request Parameters

Name	Type	Required	Description
`page`	integer	No	Page number of the result set. Defaults to 1 if not specified.
`page_size`	integer	No	Number of results to return per page. Must be between 20 and 100. Use 0 to return all results without pagination. Defaults to 20 if not specified or below the minimum.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/policies/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "schedule": {
        "id": 1,
        "timezone": "UTC",
        "minute": "0",
        "hour": "0",
        "day_of_week": "1",
        "day_of_month": "*",
        "month_of_year": "*",
        "time": "00:00:00",
        "first_occur": false,
        "start_date_time": null
      },
      "triggers": [
        {
          "id": 1,
          "pool_name": "sas1",
          "max_utilisation": null,
          "upper_threshold": null,
          "lower_threshold": null,
          "premigrate_threshold": null,
          "is_cloud": false
        }
      ],
      "order": {
        "id": 1,
        "by": "file_size",
        "reverse": false
      },
      "condition_groups": [],
      "name": "Example",
      "policy_type": "MIGRATION",
      "filesystem": "mmfs1",
      "created": "2025-06-27T14:14:31.272573Z",
      "enabled": true,
      "threads": 4,
      "site": 1,
      "spaces": [
        2
      ]
    }
  ]
}

Response Fields

Field	Description
`count`	The total number of policies available in the system (e.g., `1` policy).
`next`	URL of the next page of results (`null` if there are no more pages).
`previous`	URL of the previous page of results (`null` if there is no previous page).
`results`	An array of policy objects containing the policy details.

Policy Object (Inside results Array) - Each policy object contains the following fields:

Field	Description
`id`	The unique identifier for the policy (e.g., `1`).
`schedule`	The schedule for when the policy should run, including timing and frequency.
`triggers`	The conditions that trigger the policy, such as storage pool settings or thresholds.
`order`	Defines how the data should be processed (e.g., by file size).
`condition_groups`	Groups of conditions that must be met for the policy to be executed (e.g., `[]`).
`name`	The name of the policy (e.g., `"Example"`).
`policy_type`	The type of policy (e.g., `"MIGRATION"` for moving data).
`filesystem`	The filesystem where the policy is applied (e.g., `"mmfs1"`).
`created`	Timestamp of when the policy was created.
`enabled`	Whether the policy is enabled (`true` means enabled).
`threads`	The number of threads used for policy execution (e.g., `4`).
`site`	The site to which the policy is applied (e.g., `1`).
`spaces`	The storage spaces involved in the policy (e.g., `2`).

1.3.3. `POST` /policies/¶

Description

This API endpoint is used to create a new policy, specifying how data should be managed, processed, or migrated between storage locations.

The policy can be scheduled to run at a specific time and trigger based on conditions like storage pool utilization, file size, and other predefined conditions.

The policy can migrate data between storage tiers or to different cloud targets based on these rules.

Request Parameters

Name	Description
`data` (required)	The main body of the request. This contains the configuration for the new policy.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/policies/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

{
  "schedule": {
    "timezone": "UTC",
    "minute": "0",
    "hour": "0",
    "day_of_week": "1",
    "day_of_month": "*",
    "month_of_year": "*",
    "time": "00:00:00",
    "first_occur": false,
    "start_date_time": null
  },
  "triggers": [
    {
      "pool_name": "sas1",
      "max_utilisation": 0,
      "lower_threshold": 0,
      "upper_threshold": 0,
      "premigrate_threshold": 0,
      "is_cloud": true
    }
  ],
  "order": {
    "by": "file_size",
    "reverse": false
  },
  "name": "Test Policy",
  "policy_type": "MIGRATION",
  "filesystem": "mmfs1",
  "created": "2025-06-27T14:14:31.272573Z",
  "enabled": true,
  "threads": 4,
  "site": 1,
  "spaces": [
    2
  ]
}

Request Body Fields

schedule: Defines when the policy should execute.

Field	Description
`timezone`	The timezone to use for scheduling (set to `"UTC"`).
`minute`	Minute of the hour when the policy triggers (set to `0`).
`hour`	Hour of the day for policy execution (set to `0`, i.e., midnight).
`day_of_week`	Day of the week the policy runs (set to `1`, i.e., Monday).
`day_of_month`	Day of the month (set to `"*"`, meaning any day).
`month_of_year`	Month of the year (set to `"*"`, meaning any month).
`time`	Exact time the policy will trigger (set to `00:00:00`).
`first_occur`	Boolean flag for immediate first run (set to `false`).
`start_date_time`	When the policy becomes active (set to `null`).

Note: This configuration schedules the policy to run at midnight every Monday (UTC time).

triggers: Specifies the conditions that activate the policy.

Field	Description
`pool_name`	The name of the storage pool (e.g., `"sas1"`).
`max_utilisation`	Max storage pool utilization (set to `0`, no limit).
`lower_threshold`	Lower utilization threshold (set to `0`).
`upper_threshold`	Upper utilization threshold (set to `0`).
`premigrate_threshold`	Threshold for pre-migration actions (set to `0`).
`is_cloud`	Indicates if the pool is cloud-based (set to `true`).

Note: This configuration triggers the policy for the cloud-based pool sas1 regardless of utilization.

order: Defines how files should be processed.

Field	Description
`by`	The file order criteria (e.g., `"file_size"` to prioritize larger files).
`reverse`	Boolean flag to reverse order (set to `false`, meaning no reversal).

Note: Files will be processed from largest to smallest.

General Policy Fields

Field	Description
`name`	The name of the policy (e.g., `"Test Policy"`).
`policy_type`	The type of policy (e.g., `"MIGRATION"`).
`filesystem`	Filesystem where the policy applies (e.g., `"mmfs1"`).
`created`	Timestamp of policy creation (e.g., `"2025-06-27T14:14:31.272573Z"`).
`enabled`	Whether the policy is active (`true` means enabled).
`threads`	Number of threads for processing (e.g., `4`).
`site`	ID of the associated site (e.g., `1`).
`spaces`	List of storage space IDs (e.g., `[2]`).

Successful Response

HTTP Status Code: 201 (Created)

Content-Type: application/json

This indicates that the policy was successfully created on the server.

Example Response

{
  "id": 1,
  "schedule": {
    "timezone": "UTC",
    "minute": "0",
    "hour": "0",
    "day_of_week": "1",
    "day_of_month": "*",
    "month_of_year": "*",
    "time": "00:00:00",
    "first_occur": false,
    "start_date_time": null
  },
  "triggers": [
    {
      "pool_name": "sas1",
      "max_utilisation": 0,
      "lower_threshold": 0,
      "upper_threshold": 0,
      "premigrate_threshold": 0,
      "is_cloud": true
    }
  ],
  "order": {
    "by": "file_size",
    "reverse": false
  },
  "name": "Test Policy",
  "policy_type": "MIGRATION",
  "filesystem": "mmfs1",
  "created": "2025-06-27T14:14:31.272573Z",
  "enabled": true,
  "threads": 4,
  "site": 1,
  "spaces": [2]
}

Response Fields

The response fields are the same as the request parameters. Please refer to the section above for a better understanding.

1.3.4. `GET` /policies/{id}/¶

Description

This API endpoint retrieves detailed information about a specific policy identified by the id parameter. It returns the policy’s configuration, including its schedule, triggers, order, and other associated details.

Request Parameters

Name	Description
`id`	(Required) The unique identifier of the policy you want to retrieve. It is a string value and must be provided as part of the URL path.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/policies/1/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 1,
  "schedule": {
    "id": 1,
    "timezone": "UTC",
    "minute": "0",
    "hour": "0",
    "day_of_week": "1",
    "day_of_month": "*",
    "month_of_year": "*",
    "time": "00:00:00",
    "first_occur": false,
    "start_date_time": null
  },
  "triggers": [
    {
      "id": 1,
      "pool_name": "sas1",
      "max_utilisation": null,
      "upper_threshold": null,
      "lower_threshold": null,
      "premigrate_threshold": null,
      "is_cloud": false
    }
  ],
  "order": {
    "id": 1,
    "by": "file_size",
    "reverse": false
  },
  "condition_groups": [],
  "name": "Example",
  "policy_type": "MIGRATION",
  "filesystem": "mmfs1",
  "created": "2025-06-27T14:14:31.272573Z",
  "enabled": true,
  "threads": 4,
  "site": 1,
  "spaces": [
    2
  ]
}

Response Fields

Field Name	Description
`id`	The unique identifier for the policy. In this case, the policy ID is `1`.
`schedule`	Defines when the policy should execute based on the provided time parameters.
`triggers`	Defines the conditions that will trigger the policy.
`order`	Defines how the files will be processed during policy execution.
`condition_groups`	An empty list indicating that no condition groups are defined.
`name`	The name of the policy (e.g., `"Example"`).
`policy_type`	The type of policy (e.g., `"MIGRATION"` for data migration).
`filesystem`	The filesystem to which the policy applies (e.g., `"mmfs1"`).
`created`	The timestamp indicating when the policy was created (e.g., `2025-06-27T14:14:31.272573Z`).
`enabled`	Boolean indicating if the policy is currently active (`true`).
`threads`	Number of threads used to process files (e.g., `4`).
`site`	Site ID where the policy applies (e.g., `1`).
`spaces`	List of space IDs associated with this policy (e.g., `[2]`).

Nested Field: schedule

Field Name	Description
`schedule.id`	The unique identifier of the schedule configuration.
`schedule.timezone`	The timezone in which the policy is scheduled (e.g., `"UTC"`).
`schedule.minute`	The minute of the hour when the policy triggers (e.g., `0`).
`schedule.hour`	The hour of the day when the policy triggers (e.g., `0` for midnight).
`schedule.day_of_week`	Day of the week the policy runs (e.g., `1` for Monday).
`schedule.day_of_month`	Day of the month (set to `"*"`, meaning any day).
`schedule.month_of_year`	Month of the year (set to `"*"`, meaning any month).
`schedule.time`	Exact time the policy will trigger (e.g., `00:00:00`).
`schedule.first_occur`	Whether to start immediately on the first occurrence (`false`).
`schedule.start_date_time`	Start date and time when the policy becomes active (set to `null`).

Nested Field: triggers

Field Name	Description
`triggers.id`	The unique identifier of the trigger configuration.
`triggers.pool_name`	Storage pool name for the trigger (e.g., `"sas1"`).
`triggers.max_utilisation`	Maximum utilization threshold (set to `null`).
`triggers.upper_threshold`	Upper utilization threshold (set to `null`).
`triggers.lower_threshold`	Lower utilization threshold (set to `null`).
`triggers.premigrate_threshold`	Pre-migration threshold (set to `null`).
`triggers.is_cloud`	Whether the pool is cloud-based (`false`).

Nested Field: order

Field Name	Description
`order.id`	The unique identifier of the order configuration.
`order.by`	Criterion used for ordering files (e.g., `"file_size"`).
`order.reverse`	Whether to reverse the order (`false`).

1.3.5. `PATCH` /policies/{id}/¶

Description

This API endpoint allows updating an existing policy identified by its id. The PATCH request allows partial updates, meaning you can modify only the fields that need to be changed, such as the policy name, schedule, triggers, or other attributes.

Request Parameters

Name	Description
`id`	(Required) The unique identifier of the policy you want to update. It should be provided as part of the URL path.
`data`	(Required) A JSON object containing the updated fields of the policy.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/policies/2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json'

  "schedule": {
    "timezone": "UTC",
    "minute": "0",
    "hour": "0",
    "day_of_week": "1",
    "day_of_month": "*",
    "month_of_year": "*",
    "time": "00:00:00",
    "first_occur": false,
    "start_date_time": null
  },
  "triggers": [
    {
      "pool_name": "sas1",
      "max_utilisation": 0,
      "lower_threshold": 0,
      "upper_threshold": 0,
      "premigrate_threshold": 0,
      "is_cloud": true
    }
  ],
  "order": {
    "by": "file_size",
    "reverse": false
  },
  "name": "Test Policy Updated",
  "policy_type": "MIGRATION",
  "filesystem": "mmfs1",
  "created": "2025-06-27T14:14:31.272573Z",
  "enabled": true,
  "threads": 4,
  "site": 1,
  "spaces": [
    2
  ]

Note

For example purpose, we have updated only the name of the policy to Test Policy Updated and the creation timestamp to reflect the update time (“2025-07-07T16:42:36.971472Z”).

You can modify other parameters such as the schedule, triggers, and other settings as per your specific requirements. All other configurations, including the filesystem (mmfs1) and storage pool trigger (sas1), remain the same or can be adjusted based on your needs.

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

The server successfully processes the request, and the policy is updated with the new values.

Response Fields

Note

Refer to response fields under GET /POLICES/ID.

1.3.6. `DELETE` /policies/{id}/¶

Description

This API endpoint is used to delete a policy identified by its id. The DELETE request permanently removes the policy from the system. The deletion is typically irreversible, and once deleted, the policy cannot be restored.

Request Parameters

Name	Description
`id`	(Required) The unique identifier of the policy that you want to delete. It should be provided as part of the URL path.

Example Request

curl -X 'DELETE' \
  'http://your-hub-address:8000/api/policies/2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 204 (No Content)

The server successfully processes the request to delete the policy. A 204 No Content status code means that the request was successful, but there is no content to return in the response body. It indicates that the policy has been deleted.

Content-Type: application/json

1.3.6.1. `POST` /policies/{id}/run/¶

Description

The POST /policies/{id}/run/ endpoint allows you to manually trigger the execution of a policy identified by its id. This action forces the policy to run immediately, bypassing its regular schedule. The policy will execute based on the predefined conditions and triggers that were set during its creation.

When you make this request, a unique task_id is returned, which can be used to track the progress and status of the task.

This endpoint doesn’t require any additional parameters; the policy runs according to its current configuration.

It is particularly useful for scenarios where immediate execution is necessary, such as during urgent data migration tasks or testing, without waiting for the next scheduled trigger.

Request Parameters

Name	Description
`id`	(Required) The ID of the policy to run. It should be provided in the URL path.

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/policies/1/run/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \

This response indicates that the task has been successfully triggered. You can now track the task using the provided task_id.

Example Response

{
  "task_id": "ba14329f-7f77-4c60-9301-7bdfe36199b5"
}

Response Fields

Name	Description
`task_id`	A unique identifier for the task initiated by this request. This ID can be used to track the progress or status of the policy execution.

1.3. API Endpoint - Policies¶

1.3.1. API Reference Location¶

1.3.2. GET /policies/¶

1.3.3. POST /policies/¶

1.3.4. GET /policies/{id}/¶

1.3.5. PATCH /policies/{id}/¶

1.3.6. DELETE /policies/{id}/¶

1.3.6.1. POST /policies/{id}/run/¶

1.3.2. `GET` /policies/¶

1.3.3. `POST` /policies/¶

1.3.4. `GET` /policies/{id}/¶

1.3.5. `PATCH` /policies/{id}/¶

1.3.6. `DELETE` /policies/{id}/¶

1.3.6.1. `POST` /policies/{id}/run/¶