1.4. API Endpoints - File Management and Storage¶

1.4.1. File¶

1.4.1.1. GET /file/¶

Description

The /file/ API endpoint not only lists the files and folders under a specified path for a given site but also returns important metadata (details) about each item. These details provide valuable context about the nature, state, and attributes of each file, enabling more informed decisions and automated actions in file management systems.

Each file or folder returned by the endpoint includes a structured set of fields such as its name, type, size, creation/modification timestamps, access status, and more.

Additionally, each item is associated with a specific site. This ensures that files are clearly scoped to their respective locations, enabling secure, site-aware management and control.

Request Parameters

Parameter	Type	Required	Description
`path`	string	Yes	The target directory path to browse. (e.g., a path or virtual root).
`site`	string	Yes	The name of the site.
`page`	integer	No	Page number for paginated results. Defaults to 1.
`page_size`	integer	No	Number of items per page (20–100). Use 0 to disable pagination.
`details`	boolean	No	If true, returns detailed metadata for child files/folders. Defaults to false.
`restricted`	boolean	No	If true, includes restricted (e.g., hidden) objects. Defaults to false.
`cache_ttl`	integer	No	Duration (in seconds) for caching the result.
`type`	string	No	Filter by item type (e.g., `directory`, `file`).

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/file/?path=mmfs1&site=siteA&details=false&restricted=false' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/file/?path=mmfs1&site=siteA&details=false&restricted=false",
  "site": "siteA",
  "path": "mmfs1",
  "type": "directory",
  "size": 262144,
  "ctime": "2025-05-14T12:01:11.995371Z",
  "mtime": "2025-05-14T12:01:11.995176Z",
  "atime": "2025-06-23T14:13:11.940276Z",
  "children": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "site": "siteA",
        "path": "mmfs1/data",
        "name": "data",
        "type": "directory",
        "size": 0,
        "deleted": false,
        "restricted": false,
        "status": "online"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`url`	string	URL of the current directory view.
`site`	string	Site name the data belongs to.
`path`	string	Current directory path.
`type`	string	Always `"directory"` in this context.
`size`	integer	Size of the directory (in bytes).
`ctime`, `mtime`, `atime`	string	Creation, modification, and access timestamps (ISO format).
`children.count`	integer	Number of child items in this directory.
`children.results[]`	array	List of file or folder objects under this path.

1.4.1.2. POST /file/workflow/¶

Description

The /file/workflow/ API endpoint initiates a specified Workflow Operation on a list of files or directories within a given site.

Workflows can perform automated actions such as migration, deletion, or metadata updates on targeted file paths. This operation supports recursive discovery and accepts additional workflow-specific parameters.

Request Parameters

Parameter	Type	Required	Description
`paths`	array	Yes	List of target file or directory paths to apply the workflow to.
`site`	string	Yes	The primary site on which the workflow is executed.
`discovery`	string	Yes	How to discover files: `"recursive"` or `"flat"` (non-recursive).
`workflow`	string	Yes	Name of the workflow to execute (e.g., `migrate`, `delete`, `tag`).
`fields`	object	No	Optional workflow-specific fields. Example: `{ "lock_level": "implicit" }`

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/file/workflow/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "paths": [{"path": "/mmfs1/data/"}],
  "site": "siteA",
  "discovery": "recursive",
  "workflow": "migrate",
  "fields": {
    "lock_level": "implicit"
  }
}'

Note

In this example, the /file/workflow/ API is used to trigger a migrate workflow on the directory /mmfs1/data/ within the given site.

The "discovery": "recursive" parameter means the workflow applies to the specified directory and all of its contents, including files and nested subdirectories.

The "fields" section sets "lock_level": "implicit", which controls how files are locked or reserved during the migration process.

The response confirms that a migration job has started, providing a job ID, status (STARTED), and a list of task IDs representing the operations in progress.

This kind of workflow is useful for moving data across storage systems, preparing content for processing, or archiving large data sets within a site managed by the Hub.

Successful Response

HTTP Status Code: 201 Created

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/jobs/38/",
  "id": 38,
  "workflow": "migrate",
  "fields": {
    "lock_level": "implicit"
  },
  "created": "2025-06-24T13:17:09.771857Z",
  "started": "2025-06-24T13:17:09.818646Z",
  "completed": null,
  "runtime": 0.088984,
  "state": "STARTED",
  "site": "siteA",
  "queue": "default",
  "owner": {
    "type": "user",
    "id": 2,
    "name": "hubadmin"
  },
  "discovery": "recursive",
  "is_settings_job": false,
  "friendly_name": "Dehydrate of '/mmfs1/data/' on 'siteA'",
  "progress": null,
  "tasks": [266, 265, 267]
}

Response Fields

Field	Type	Description
`id`	integer	Job ID representing the submitted workflow operation.
`url`	string	API link to check job status and details.
`workflow`	string	Name of the executed workflow.
`fields`	object	Workflow-specific parameters used in this execution.
`created`	datetime	Timestamp when the job was created.
`started`	datetime	Timestamp when execution started.
`completed`	datetime	Timestamp when execution completed (`null` if still running).
`runtime`	float	Time (in seconds) taken so far.
`state`	string	Current job state: `STARTED`, `COMPLETED`, `FAILED`, etc.
`site`	string	Site where the workflow was executed.
`queue`	string	Job queue used, usually `"default"`.
`owner`	object	User who triggered the job (includes `id`, `name`, `type`).
`discovery`	string	Discovery mode used (`recursive` or `flat`).
`friendly_name`	string	Human-readable job description.
`progress`	object/null	Progress tracking info (`null` if not yet tracked).
`tasks`	array	List of task IDs spawned by this job.

1.4.2. Filesystems¶

1.4.2.1. GET /filesystems/¶

Description

The /filesystems/ API endpoint retrieves a list of available file systems across all configured sites. Each file system is associated with a specific site and includes basic metadata such as its name and mount point.

This endpoint is particularly useful, where each site may host its own instance of a distributed file system (e.g., GPFS/Spectrum Scale), and operations need to be scoped accordingly.

Note

A filesystem is a structured method of storing, organizing, and accessing data on a storage device.

In multi-site platforms like Ngenea Hub, a filesystem refers to a mounted storage volume, such as mmfs1 that exists within a specific site. Each filesystem is uniquely identified by its name and mount point, and it serves as the root for all file and directory operations within that site.

This logical storage environment serves as the root for files, directories, and filesets within the associated site.

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/filesystems/?page=1&page_size=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": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "mmfs1",
      "site": "siteA",
      "mountpoint": "/mmfs1"
    },
    {
      "name": "mmfs1",
      "site": "siteB",
      "mountpoint": "/mmfs1"
    }
  ]
}

Response Fields

Top-Level Fields

Field	Type	Description
`count`	integer	Total number of file systems across all pages.
`next`	string	URL to the next page of results (if any).
`previous`	string	URL to the previous page of results (if any).
`results`	array	List of file systems with their metadata.

Each item in the results array contains:

Field	Type	Description
`name`	string	Name of the file system (e.g., `mmfs1`).
`site`	string	Name of the site where this file system is mounted.
`mountpoint`	string	Mount path of the file system on that site.

1.4.2.2. GET /filesystems/{id}/¶

Description

The GET /filesystems/{id}/ endpoint retrieves detailed information about a specific filesystem space by its unique ID. This is useful for querying metadata about a filesystem space associated with a particular site—such as its name and mount location.

This endpoint is typically used when you already know the filesystem’s ID (from a /filesystems/ list call) and want to fetch more focused data for display or internal logic.

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the filesystem.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/filesystems/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

{
  "name": "mmfs1",
  "site": "siteA",
  "mountpoint": "/mmfs1"
}

Response Fields

Please check the above endpoint to understand the response field.

1.4.3. Filesets¶

A fileset is a logical subdivision of a filesystem, used to organize, manage, and apply policies to files in a more granular way. In Ngenea Hub, a fileset is automatically created when a space is created.

It provides an isolated namespace within a filesystem, allowing for features such as:

Independent data management (e.g., quota, snapshots)
Enhanced access control
Simplified backup and archiving

Note

The term “fileset” comes from its role: a set of files grouped by policy, location, or purpose within a larger filesystem. This abstraction helps manage large-scale data more efficiently.

1.4.3.1. GET /filesets/¶

Description

This API endpoint allows users to retrieve all filesets for a specific site.

Request Parameters

Name	Type	Location	Required	Description
`site`	string	query	Yes	Name of the site (minimum 1 character) where file sets are defined.

Example Request

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

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

[
  {
    "path": "/mmfs1/data/Test_Space",
    "site": "qatest-pdevan-testplugin-siteA",
    "name": "sas1-Test_Space",
    "label": "sas1-Test_Space",
    "filesystem": "mmfs1"
  }
]

Response Fields

Field	Type	Description
`path`	string	Full path to the fileset within the filesystem.
`site`	string	The name of the site the fileset belongs to.
`name`	string	The internal name of the fileset.
`label`	string	The display label of the fileset.
`filesystem`	string	The parent filesystem this fileset resides in.

1.4.4. Sites¶

In Ngenea Hub, a site represents a distinct location or system within the Ngenea Hub ecosystem where data and events are managed and synchronized. Each site is identified by a unique name, which is crucial for tracking, managing, and reflecting events (such as file updates or deletions) across the distributed environment.

1.4.4.1. GET /sites/¶

Description

The GET /sites/ endpoint allows you to retrieve a list of all sites registered in your Ngenea Hub system. Each site represents a physical or cloud-based server managed by the Hub. The endpoint supports pagination and provides detailed metadata about each site, such as its name, type, associated storage spaces, and file statistics.

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/sites/?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": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "http://your-hub-address:8000/api/sites/1/",
      "id": 1,
      "name": "siteA",
      "shortcode": "CXL",
      "label": "siteA",
      "am_i_configured": true,
      "bandwidth": 0,
      "spaces": ["mmfs1", "Test_Space"],
      "type": "CLOUD",
      "directories_count": 317,
      "files_count": 977,
      "files_hydrated_count": 977,
      "files_stubbed_count": 0,
      "editable": true,
      "public_url": "https://your-hub-address",
      "color": [170, 232, 242],
      "ready_to_configure": true
    },
    {
      "url": "http://your-hub-address:8000/api/sites/2/",
      "id": 2,
      "name": "siteB",
      "shortcode": "I17",
      "label": "siteB",
      "am_i_configured": true,
      "bandwidth": 0,
      "spaces": ["mmfs1"],
      "type": "CLOUD",
      "directories_count": 317,
      "files_count": 1001,
      "files_hydrated_count": 1001,
      "files_stubbed_count": 0,
      "editable": true,
      "public_url": "https://10.201.2.185",
      "color": [227, 170, 242],
      "ready_to_configure": true
    }
  ]
}

Response Fields

Top-Level Fields

Field	Type	Description
`count`	integer	Total number of sites available.
`next`	string/null	URL to the next page of results, or `null` if none.
`previous`	string/null	URL to the previous page of results, or `null` if none.
`results`	array	List of site objects returned for the current page.

results[] Object Fields

Field	Type	Description
`url`	string	API URL for the specific site resource.
`id`	integer	Unique identifier of the site.
`name`	string	Name of the site.
`shortcode`	string	Short code representing the site.
`label`	string	Label for the site.
`am_i_configured`	boolean	Indicates if the site is configured.
`bandwidth`	integer	Bandwidth limit for the site.
`spaces`	array of strings	List of associated spaces for the site.
`type`	string	Type of the site (e.g., `"CLOUD"`).
`directories_count`	integer	Number of directories in the site.
`files_count`	integer	Total number of files in the site.
`files_hydrated_count`	integer	Number of hydrated files.
`files_stubbed_count`	integer	Number of stubbed files.
`editable`	boolean	Whether the site is editable.
`public_url`	string	Public URL to access the site.
`color`	array of integers	RGB color values representing the site color.
`ready_to_configure`	boolean	Indicates if the site is ready to be configured.

1.4.4.2. POST /sites/¶

Description

Creates a new site with the specified properties, including spaces, name, configuration parameters, and metadata.

Request Parameters

Name	Type	Location	Description
`data`	object	body	JSON object containing the site details and configuration settings.

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/sites/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "spaces": ["mmfs1"],
    "name": "testexample",
    "shortcode": "str",
    "file_batch_size": 40,
    "file_batch_gb": 1,
    "enable_auto_file_batch_sizing": true,
    "lock_threshold": 86400,
    "bandwidth": 0,
    "elasticsearch_url": "localhost:9200",
    "pixstor_search_url": "https://localhost",
    "public_url": "https://pixstor-mn-001",
    "include": [],
    "exclude": [],
    "label": "string",
    "am_i_configured": true,
    "type": "CLOUD",
    "color": [242, 170, 235],
    "files_count": 2147483647,
    "directories_count": 2147483647,
    "files_stubbed_count": 2147483647,
    "files_hydrated_count": 2147483647,
    "gpfs_iscan_buckets": 2147483647,
    "gpfs_iscan_threads": 2147483647,
    "ready_to_configure": true
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 3,
  "url": "http://10.201.2.224:8000/api/sites/3/",
  "name": "testexample",
  "shortcode": "str",
  "label": "string",
  "spaces": ["mmfs1"],
  "file_batch_size": 40,
  "file_batch_gb": 1,
  "enable_auto_file_batch_sizing": true,
  "lock_threshold": 86400,
  "bandwidth": 0,
  "elasticsearch_url": "localhost:9200",
  "pixstor_search_url": "https://localhost",
  "public_url": "https://pixstor-mn-001",
  "include": [],
  "exclude": [],
  "am_i_configured": true,
  "type": "CLOUD",
  "color": [242, 170, 235],
  "files_count": 2147483647,
  "directories_count": 2147483647,
  "files_stubbed_count": 2147483647,
  "files_hydrated_count": 2147483647,
  "gpfs_iscan_buckets": 2147483647,
  "gpfs_iscan_threads": 2147483647,
  "ready_to_configure": true,
  "editable": true
}

Response Fields

Refer to the requests body fields under GET/SITES.

1.4.4.3. GET /sites/{id}/¶

Description

Retrieves detailed information about a specific site by its unique ID.

Request Parameters

Name	Type	Location	Description
`id`	string	path	The unique ID of the site.

Example Request

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

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/sites/2/",
  "spaces": [
    {
      "url": "http://your-hub-address:8000/api/spaces/1/",
      "id": 1,
      "name": "mmfs1"
    }
  ],
  "editable": true,
  "id": 2,
  "name": "siteB",
  "shortcode": "I17",
  "file_batch_size": 40,
  "file_batch_gb": 1,
  "enable_auto_file_batch_sizing": true,
  "lock_threshold": 86400,
  "bandwidth": 0,
  "elasticsearch_url": "localhost:19200",
  "pixstor_search_url": null,
  "public_url": "https://10.201.2.185",
  "include": null,
  "exclude": null,
  "label": "siteB",
  "am_i_configured": true,
  "type": "CLOUD",
  "color": [227, 170, 242],
  "files_count": 1001,
  "directories_count": 317,
  "files_stubbed_count": 0,
  "files_hydrated_count": 1001,
  "gpfs_iscan_buckets": null,
  "gpfs_iscan_threads": null,
  "ready_to_configure": true
}

Response Fields

Refer to the requests body fields under GET/SITES.

1.4.4.4. PATCH /sites/{id}/¶

Description

Updates an existing site’s properties using partial or full data. Only the fields included in the request will be updated.

Request Parameters

Name	Type	Location	Description
`id`	string	path	The unique ID of the site to update.
`data`	object	body	JSON object containing the fields to update.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/sites/3/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "spaces": ["mmfs1"],
    "name": "testexample",
    "shortcode": "Te",
    "label": "string"
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/sites/3/",
  "spaces": [
    {
      "url": "http://your-hub-address:8000/api/spaces/1/",
      "id": 1,
      "name": "mmfs1"
    }
  ],
  "editable": true,
  "id": 3,
  "name": "testexample",
  "shortcode": "Te",
  "label": "string",
  "type": "CLOUD",
  "ready_to_configure": true
}

Note

The site with ID 3 was successfully updated with example values (e.g., shortcode: “Te”, label: “TestEx”). Any subset of parameters can be provided in the PATCH request to update specific fields as per user requirements.

Response Fields

The response includes all updated site fields. These are the same as those returned in GET /sites/{id}/.

1.4.4.5. DELETE /sites/{id}/¶

Description

Deletes a specific site identified by its unique ID.

Request Parameters

Name	Type	Location	Description
`id`	string	path	The unique ID of the site.

Example Request

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

Successful Response

HTTP Status Code: 204 No Content — No response body returned.

Note

Site with ID 4 was deleted. This operation is irreversible. Ensure the correct ID is passed, as all associated metadata and configuration will be permanently removed.

1.4.4.6. GET /sites/{id}/health/¶

Description Retrieves the health status of a specific site, including the health of its nodes and queues.

Health represents the overall operational status of the site and its components, indicating whether they are functioning correctly, online, and responsive. A status of “ok” means the site and its nodes and queues are running normally without issues.

Request Parameters

Name	Type	Location	Description
`id`	string	path	The unique ID of the site.

Example Request

curl -X 'GET' \
  'http://10.201.2.224:8000/api/sites/2/health/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "site": "qatest-pdevan-testplugin-siteB",
  "health": "ok",
  "nodes": [
    {
      "name": "qatest-pdevan-testplugin-siteB-1",
      "health": "ok",
      "online": true,
      "has_default_queue": true,
      "last_heartbeat": "2025-07-03T15:34:59.540149+00:00",
      "worker_version": "2.6.0",
      "ngenea_version": "1.31.0",
      "analytics_version": "2.7.1",
      "search_version": "1.2.0"
    }
  ],
  "queues": [
    {
      "name": "default",
      "health": "ok",
      "online": true,
      "last_heartbeat": "2025-07-03T15:35:09.552068+00:00"
    }
  ]
}

Response Fields

Site Health Response Fields

Field	Type	Description
`site`	string	Name of the site.
`health`	string	Overall health status of the site (e.g., `ok`).
`nodes`	array	List of node health objects.

nodes[] Object Fields

Field	Type	Description
`nodes[].name`	string	Name of the node.
`nodes[].health`	string	Health status of the node.
`nodes[].online`	boolean	Whether the node is online.
`nodes[].has_default_queue`	boolean	Whether the node has a default queue configured.
`nodes[].last_heartbeat`	string	Timestamp of the last heartbeat received from the node.
`nodes[].worker_version`	string	Version of the worker component (if available).
`nodes[].ngenea_version`	string	Version of the ngenea component (if available).
`nodes[].analytics_version`	string	Version of the analytics module (if available).
`nodes[].search_version`	string	Version of the search module (if available).
`nodes[].version_details`	string	Version fetch status message (if any errors).

queues[] Object Fields

Field	Type	Description
`queues[].name`	string	Queue name (e.g., `default`).
`queues[].health`	string	Health status of the queue.
`queues[].online`	boolean	Whether the queue is online.
`queues[].last_heartbeat`	string	Timestamp of the last heartbeat from the queue.

1.4.4.7. POST /sites/{id}/refresh/¶

Description

Triggers a refresh operation for the specified site, which may include updating analytics, fetching remote servers, loading storage pools, and checking space/site quotas asynchronously.

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/sites/2/refresh/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -d ''

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

{
  "dynamocore.tasks.site.fetch_site_analytics": "4fb5b60a-630e-4adb-b946-2c555184f0a4",
  "dynamocore.tasks.server.get_remote_servers": "900d2b0e-1c78-422e-82c7-c6ac84a9693c",
  "dynamocore.tasks.admin.load_storagepools": "7edadbc1-c400-4d19-b0b5-6af348085e5c",
  "dynamocore.tasks.space_site.send_check_space_site_quota": "34d94c8b-d4e4-4357-bf65-d589f920dbd6"
}

Response Fields

Field	Type	Description
Task names as keys	string	Identifiers for the triggered asynchronous tasks.
Task IDs as values	string	UUIDs representing each task instance.

1.4.4.8. GET /sites/{id}/settings/¶

Description

This API endpoint retrieves the configuration settings for a specific site identified by its id. These settings control various operational parameters such as backup schedules, logging, monitoring, network configurations, and other system behaviors related to the site.

Accessing site settings is essential for administrators or automated systems to review, audit, or adjust the configurations without direct access to the server. It allows monitoring of the current configuration state and supports troubleshooting, compliance checks, and dynamic adjustments to the site behavior.

Request Parameters

Name	Type	Location	Description
`id`	string	path	The unique identifier of the site.
`flat`	boolean	query	Return settings as a flat dictionary (`true` or `false`, default: `false`).

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/sites/2/settings/?flat=false' \
  -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": 32,
    "key": "apbackup:schedule",
    "value": "*-*-* 01:00:00",
    "desc": "The systemd calendar event for configuring the systemd timer service that runs apbackup."
  },
  {
    "id": 36,
    "key": "email:arcapix_alert_address",
    "value": "alerts@pixitmedia.com",
    "desc": "Description not specified"
  },
  {
    "id": 37,
    "key": "monitoring:auth:monitoring_internal",
    "value": "********************",
    "desc": "Description not specified"
  },
  {
    "id": 42,
    "key": "ntp:servers",
    "value": [
      "0.centos.pool.ntp.org",
      "1.centos.pool.ntp.org",
      "2.centos.pool.ntp.org",
      "3.centos.pool.ntp.org"
    ],
    "desc": "list of NTP servers"
  }
  // more settings ...
]

Response Fields

Field	Description
`id`	Setting unique identifier.
`key`	The setting key name.
`value`	The setting value (may be string, bool, array, etc.).
`desc`	Description of the setting (may be `null` or unspecified).

1.4.4.9. POST /sites/{id}/settings/refresh/¶

Description

The POST /sites/{id}/settings/refresh/ endpoint is used to refresh the settings for a specific site identified by id. This action can be used to update existing settings or create settings in the Ngenea Hub if none exist for the given site. It’s an asynchronous process, meaning the operation will be carried out in the background, and you can track its progress via a task ID.

Request Parameters

Name	Type	Location	Description
`id`	string	path	Required. Unique identifier of the site to refresh settings for. This is part of the URL path. Example: `/sites/2/settings/refresh/`

Example Request

curl -X 'POST' \
  'http://10.201.2.224:8000/api/sites/2/settings/refresh/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -d ''

Successful Response

HTTP Status Code: 202 Accepted

This indicates that the request has been accepted and is now being processed, but the operation has not completed yet. The task is running asynchronously, so you can track its progress with the task_id.

Content-Type: application/json

Example Response

{
  "task_id": "201ef094-5e55-42b7-818b-1e586c52bda0"
}

Response Fields

Field	Type	Description
`task_id`	string	A unique identifier for the refresh task. Use this ID to track its progress or retrieve status.

1.4.5. Shares¶

Shares are designated directories or access points within the Pixstor storage system that are made available to external systems over a network. These shares allow remote clients to access, read, write, or manage data stored in the Pixstor environment as if it were part of their local file system.

These shares can be accessed using various protocols like NFS (for Linux/Unix-based clients) and Samba (for Windows and other SMB-compatible clients).

NFS and Samba are two common protocols for sharing files, with NFS being primarily used for Linux-based environments and Samba providing cross-platform compatibility for Windows and Linux systems.

1.4.5.1. GET /shares/nfs/¶

The GET /shares/nfs/ endpoint is used to retrieve a list of NFS shares from your storage system. NFS (Network File System) shares allow remote clients to access the file system over a network. This API call provides details of all NFS shares currently configured, including their associated settings, clients, and more.

Request Parameters

No parameters - This endpoint does not require any parameters in the request query. The response will return a list of all NFS shares.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/shares/nfs/' \
  -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,
    "uuid": "a4255625-e9d9-4a72-817a-719cfd69d73e",
    "space": 2,
    "clients": [
      {
        "id": 1,
        "hosts": "*",
        "force_root_user_id": false,
        "force_all_user_id": false,
        "asynchronous": false,
        "write_delay": true,
        "insecure_ports": false,
        "subtree_check": true,
        "advanced_settings": null,
        "read_only": false,
        "anonymous_user_id": 65534,
        "anonymous_group_id": 65534,
        "uuid": "4edbd055-7ec6-4a3f-9b80-cde5d6f0d55d",
        "nfs_share": 1
      }
    ],
    "path": "/mmfs1/data/Test_Space",
    "name": "test2",
    "fsid": 55102
  },
  {
    "id": 3,
    "uuid": "67aedd4b-60ee-462d-8673-0d8f662fae7b",
    "space": 1,
    "clients": [
      {
        "id": 2,
        "hosts": "string",
        "force_root_user_id": null,
        "force_all_user_id": true,
        "asynchronous": true,
        "write_delay": true,
        "insecure_ports": true,
        "subtree_check": true,
        "advanced_settings": {},
        "read_only": true,
        "anonymous_user_id": 2147483647,
        "anonymous_group_id": 2147483647,
        "uuid": "28a181ef-2c56-4e03-b64d-49f5082fda4a",
        "nfs_share": 3
      }
    ],
    "path": "/mmfs1/data/API_Example",
    "name": "test5",
    "fsid": 65535
  }
]

Response Fields

Field	Description
`id`	The unique identifier for the NFS share.
`uuid`	A unique identifier for the NFS share.
`space`	The storage pool associated with this NFS share. Corresponds to the space identifier.
`clients`	A list of client configurations (who can access the share). Each includes access settings.
`path`	The file system path for the NFS share (e.g., `/mmfs1/data/Test_Space`).
`name`	The name of the NFS share.
`fsid`	The file system identifier (FSID) representing the file system for this share.

1.4.5.2. POST /shares/nfs/¶

Description

This request is used to create a new NFS share. The share can be accessed remotely by clients that support the NFS protocol.

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/shares/nfs/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "/mmfs1",
    "name": "Test1",
    "space": 1,
    "clients": [
      {
        "hosts": "*",
        "read_only": false
      }
    ]
  }'

Request Body Fields

NFS Share Configuration Fields

Field	Type	Description
`path`	string	Directory path of the NFS share (e.g., `/mmfs1`).
`name`	string	Name of the NFS share (e.g., `"Test1"`).
`space`	integer	Space ID where the share is created (system managed).
`clients[]`	object	List of client configurations defining access permissions.
`hosts`	string	Hosts that can access the share (e.g., `*` for all hosts).
`read_only`	boolean	If `true`, makes the share read-only for clients (default: `false`).

Optional Fields

Field	Type	Description
`force_root_user_id`	boolean	If `true`, map requests from uid/gid 0 to the anonymous uid/gid.
`force_all_user_id`	boolean	If `true`, maps all users to a specific user ID when accessing the share.
`asynchronous`	boolean	If `true`, enables async writes (faster but risks data loss on failure).
`write_delay`	boolean	If `true`, enables write delay to enhance performance.
`insecure_ports`	boolean	If `true`, allows access from insecure (non-privileged) ports.
`subtree_check`	boolean	If `true`, enables subtree integrity checks when moving/renaming files.
`advanced_settings`	object	Placeholder for advanced or custom configurations.
`anonymous_user_id`	integer	User ID for anonymous access (e.g., `65534` for “nobody”).
`anonymous_group_id`	integer	Group ID for anonymous access (e.g., `65534` for “nobody”).
`uuid`	string	UUID of the client configuration (system generated).
`nfs_share`	integer	ID of the NFS share associated with this client config (auto-assigned).

Successful Response

HTTP Status Code: 201 CREATED

Content-Type: application/json

Example Response

{
  "id": 5,
  "uuid": "3eae699e-c148-4179-ac36-b94a4d5f4dc0",
  "space": 1,
  "clients": [
    {
      "id": 4,
      "hosts": "*",
      "force_root_user_id": null,
      "force_all_user_id": null,
      "asynchronous": null,
      "write_delay": null,
      "insecure_ports": null,
      "subtree_check": null,
      "advanced_settings": null,
      "read_only": false,
      "anonymous_user_id": null,
      "anonymous_group_id": null,
      "uuid": "948bed6b-a87c-4b2d-8d38-3fd88ee5599a",
      "nfs_share": 5
    }
  ],
  "path": "/mmfs1",
  "name": "Test1",
  "fsid": 19904
}

Response Fields

Field	Type	Description
`id`	integer	The unique identifier for the newly created NFS share.
`uuid`	string	The UUID of the NFS share.
`space`	integer	The space (ID) where the share was created.
`clients`	array	List of client settings for the share, including host and permission info.
`clients[]`	object	Client-specific settings. Each includes `id`, `hosts`, `read_only`, etc.
`path`	string	The path of the directory being shared (e.g., `/mmfs1`).
`name`	string	The name of the share (e.g., `"Test1"`).
`fsid`	integer	The filesystem ID that represents the share’s filesystem.

1.4.5.3. GET /shares/nfs/{id}/¶

Description

This endpoint retrieves detailed information about a specific NFS share, identified by its id. The data returned includes the NFS share’s properties such as the share’s path, name, associated space, and client configurations.

Request Parameters

Name	Description
`id`	Required. The unique integer identifier of the NFS share. Used as a path parameter in API requests.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/shares/nfs/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,
  "uuid": "a4255625-e9d9-4a72-817a-719cfd69d73e",
  "space": 2,
  "clients": [
    {
      "id": 1,
      "hosts": "*",
      "force_root_user_id": false,
      "force_all_user_id": false,
      "asynchronous": false,
      "write_delay": true,
      "insecure_ports": false,
      "subtree_check": true,
      "advanced_settings": null,
      "read_only": false,
      "anonymous_user_id": 65534,
      "anonymous_group_id": 65534,
      "uuid": "4edbd055-7ec6-4a3f-9b80-cde5d6f0d55d",
      "nfs_share": 1
    }
  ],
  "path": "/mmfs1/data/Test_Space",
  "name": "test2",
  "fsid": 55102
}

Response Fields

Refer to the response fields under GET/Shares/NFS/.

1.4.5.4. GET /shares/samba/¶

Description

This endpoint retrieves a list of all Samba shares available in the system, providing details like share name, access settings, and visibility.

Request Parameters : No parameters required for this request.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/shares/samba/' \
  -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,
    "path": "/mmfs1",
    "uuid": "1406dc83-124c-4028-8b9d-8a0ef8c3b375",
    "hosts_allow": [],
    "hosts_deny": [],
    "admin_users": [],
    "allowed_users": [],
    "name": "Test1",
    "read_only": false,
    "visible": true,
    "create_mask": null,
    "directory_mask": null,
    "advanced_settings": {},
    "multi_thread_reads": true,
    "multi_thread_writes": true,
    "root_share_locking": true,
    "hsm_support": true,
    "guest_ok": false,
    "force_create_mode": null,
    "force_directory_mode": null,
    "space": 1
  },
  /////////////////////////////////// - Sites info
]

Response Fields

Field	Description
`id`	A unique identifier for the samba share.
`path`	The path to the shared directory in the file system (e.g., `/mmfs1`).
`uuid`	A universally unique identifier (UUID) for the samba share.
`hosts_allow`	List of allowed client hosts for accessing the share. Empty if no specific hosts are allowed.
`hosts_deny`	List of denied client hosts for accessing the share. Empty if no specific hosts are denied.
`admin_users`	List of users with administrative access to the share.
`allowed_users`	List of users permitted to access the share.
`name`	The name of the samba share (e.g., `Test1`).
`read_only`	Boolean indicating if the share is read-only. `true` means read-only; users can only view or read data but cannot modify it.
`visible`	Boolean indicating if the share is visible to clients.
	- `true`: Clients can see and browse the share.
	- `false`: Clients cannot see the share during normal browsing, but access is still possible if the path is known.
`create_mask`	Permissions mask for creating new files in the share.
`directory_mask`	Permissions mask for directories in the share.
`advanced_settings`	Advanced settings for the samba share (if any). Can be an empty object if no advanced settings exist.
`multi_thread_reads`	Boolean indicating whether multi-threaded reads are enabled.
`multi_thread_writes`	Boolean indicating whether multi-threaded writes are enabled.
`root_share_locking`	Boolean indicating if root share locking is enabled.
`hsm_support`	Boolean indicating if HSM (Hierarchical Storage Management) is supported.
`guest_ok`	Boolean indicating if guest access is allowed to the share.
`force_create_mode`	File creation mode enforced on the share, if any.
`force_directory_mode`	Directory creation mode enforced on the share, if any.
`space`	The storage space identifier associated with the share.

1.4.5.5. POST /shares/samba/¶

Description

The POST /shares/samba/ endpoint is used to create a new Samba share on the server. You must send a request with details like the share’s name, path, and visibility settings.

Additionally, you can specify which clients are allowed access to the share, along with specific permissions (read-only or full access).

Example Request

curl -X POST \
  http://your-hub-address:8000/api/shares/samba/ \
  -H "accept: application/json" \
  -H "Authorization: Api-Key your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/mmfs1",
    "name": "Test9",
    "space": 1,
    "read_only": true,
    "visible": true,
    "clients": [
      {
        "hosts": "*",
        "read_only": false
      }
    ]
  }'

Request Body Fields

Field	Description	Example
`path`	The directory path to be shared via Samba.	`/mmfs1`
`name`	The name of the Samba share.	`Test9`
`space`	The storage space ID that this share will be linked to.	`1`
`read_only`	If set to `true`, the share is read-only for all users.	`true`
`visible`	If set to `true`, the share is visible to clients.	`true`
`clients`	A list of client configurations specifying which clients can access the share.	`[{"hosts": "*", "read_only": false}]`

Successful Response

HTTP Status Code: 201 CREATED

Content-Type: application/json

Example Response

{
  "id": 2,
  "path": "/mmfs1",
  "uuid": "bb4f28ae-996d-4e68-b973-e9c36238cb43",
  "hosts_allow": [],
  "hosts_deny": [],
  "admin_users": [],
  "allowed_users": [],
  "name": "Test9",
  "read_only": true,
  "visible": true,
  "create_mask": null,
  "directory_mask": null,
  "advanced_settings": {},
  "multi_thread_reads": false,
  "multi_thread_writes": false,
  "root_share_locking": false,
  "hsm_support": false,
  "guest_ok": false,
  "sites": {},
  "force_create_mode": null,
  "force_directory_mode": null,
  "space": 1
}

Response Fields

Refer to the response fields under GET/Shares/Samba.

1.4.5.6. GET /shares/samba/{id}/¶

Description

This API endpoint retrieves the details of a specific Samba share based on its unique ID. It returns metadata, configuration settings, and site-specific share information.

Request Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	A unique integer value identifying the Samba share.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/shares/samba/3/' \
  -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": 3,
  "path": "/mmfs1",
  "uuid": "f01ab517-6b70-4bd8-8d60-9f7e9b3a7a58",
  "hosts_allow": {},
  "hosts_deny": {},
  "admin_users": {},
  "allowed_users": {},
  "name": "Samba Test",
  "read_only": true,
  "visible": true,
  "create_mask": "null",
  "directory_mask": "null",
  "advanced_settings": {},
  "multi_thread_reads": true,
  "multi_thread_writes": true,
  "root_share_locking": true,
  "hsm_support": true,
  "guest_ok": true,
  "sites": {
    "siteA": {
      "name": "Samba Test",
      "path": "/mmfs1",
      "present": true,
      "visible": true,
      "guest_ok": true,
      "read_only": true,
      "hosts_deny": {},
      "admin_users": {},
      "create_mask": "null",
      "hosts_allow": {},
      "hsm_support": true,
      "allowed_users": {},
      "directory_mask": "null",
      "advanced_settings": {},
      "multi_thread_reads": true,
      "root_share_locking": true,
      "multi_thread_writes": true
    },
    "siteB": {
      "name": "Samba Test",
      "path": "/mmfs1",
      "present": true,
      "visible": true,
      "guest_ok": true,
      "read_only": true,
      "hosts_deny": {},
      "admin_users": {},
      "create_mask": "null",
      "hosts_allow": {},
      "hsm_support": true,
      "allowed_users": {},
      "directory_mask": "null",
      "advanced_settings": {},
      "multi_thread_reads": true,
      "root_share_locking": true,
      "multi_thread_writes": true
    }
  },
  "force_create_mode": null,
  "force_directory_mode": null,
  "space": 1
}

Response Fields

Field	Type	Description
`id`	integer	Unique ID of the Samba share
`path`	string	Path of the share on the filesystem
`uuid`	string	Unique identifier (UUID) for the Samba share
`hosts_allow`	object	List of allowed hosts (empty if unrestricted)
`hosts_deny`	object	List of denied hosts (empty if unrestricted)
`admin_users`	object	Admin users for the share (empty if none)
`allowed_users`	object	Allowed users for the share (empty if unrestricted)
`name`	string	Human-readable name of the share
`read_only`	boolean	Indicates if the share is read-only
`visible`	boolean	Indicates if the share is visible
`create_mask`	string	File permission mask on file creation (often null or a string like `"0777"`)
`directory_mask`	string	Directory permission mask on directory creation
`advanced_settings`	object	Advanced Samba configuration settings (if any)
`multi_thread_reads`	boolean	Whether multi-threaded reads are enabled
`multi_thread_writes`	boolean	Whether multi-threaded writes are enabled
`root_share_locking`	boolean	Indicates if root share locking is enabled
`hsm_support`	boolean	Whether HSM (Hierarchical Storage Management) support is enabled
`guest_ok`	boolean	Whether guest access is allowed
`sites`	object	Site-specific configuration and presence info (keyed by site name)
`force_create_mode`	string	Optional enforced file create mode (null if not set)
`force_directory_mode`	string	Optional enforced directory create mode (null if not set)
`space`	integer	Logical identifier or grouping reference (may represent tenant/project)

1.4.5.7. PATCH /shares/samba/{id}/¶

Description

This endpoint allows partial updates to an existing Samba share identified by its id. Only specific fields are allowed to be updated as listed below. Any attempt to update other fields may result in validation errors or be ignored by the backend.

Request Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	A unique integer value identifying the Samba share.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/shares/samba/3/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "/mmfs1",
  "name": "Samba Test Updated",
  "read_only": true,
  "visible": true,
  "advanced_settings": {},
  "multi_thread_reads": true,
  "multi_thread_writes": true,
  "root_share_locking": true,
  "hsm_support": true,
  "guest_ok": true,
  "sites": {
    "siteA": {
      "name": "Samba Test Updated",
      "path": "/mmfs1",
      "present": true,
      "visible": true,
      "guest_ok": true,
      "read_only": true,
      "hosts_deny": {},
      "admin_users": {},
      "create_mask": "null",
      "hosts_allow": {},
      "hsm_support": true,
      "allowed_users": {},
      "directory_mask": "null",
      "advanced_settings": {},
      "multi_thread_reads": true,
      "root_share_locking": true,
      "multi_thread_writes": true
    }
  },
  "space": 1
}
'

Request Body Fields

Field	Type	Description
`hosts_allow`	object	Hosts allowed to access the share
`hosts_deny`	object	Hosts denied from accessing the share
`admin_users`	object	Admin users with elevated privileges
`allowed_users`	object	Regular users allowed to access the share
`name`	string	Display name of the Samba share
`read_only`	boolean	If `true`, the share is read-only
`visible`	boolean	If `true`, the share is visible to users
`create_mask`	string	File creation permission mask (e.g., `"0755"`)
`directory_mask`	string	Directory creation permission mask (e.g., `"0755"`)
`advanced_settings`	object	Additional advanced Samba settings
`multi_thread_reads`	boolean	Enable multi-threaded read operations
`multi_thread_writes`	boolean	Enable multi-threaded write operations
`root_share_locking`	boolean	Enable locking at the root share level
`hsm_support`	boolean	Enable Hierarchical Storage Management (HSM) support
`guest_ok`	boolean	If `true`, guest access is allowed
`force_create_mode`	string	Enforced file create mode (e.g., `"0755"`)
`force_directory_mode`	string	Enforced directory create mode (e.g., `"0755"`)

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 3,
  "path": "/mmfs1",
  "uuid": "f01ab517-6b70-4bd8-8d60-9f7e9b3a7a58",
  "hosts_allow": {},
  "hosts_deny": {},
  "admin_users": {},
  "allowed_users": {},
  "name": "Samba Test Updated",
  "read_only": true,
  "visible": true,
  "create_mask": "null",
  "directory_mask": "null",
  "advanced_settings": {},
  "multi_thread_reads": true,
  "multi_thread_writes": true,
  "root_share_locking": true,
  "hsm_support": true,
  "guest_ok": true,
  "on_sites": {
    "siteA": {
      "name": "Samba Test Updated",
      "path": "/mmfs1",
      "present": true,
      "visible": true,
      "guest_ok": true,
      "read_only": true,
      "hosts_deny": {},
      "admin_users": {},
      "create_mask": "null",
      "hosts_allow": {},
      "hsm_support": true,
      "allowed_users": {},
      "directory_mask": "null",
      "advanced_settings": {},
      "multi_thread_reads": true,
      "root_share_locking": true,
      "multi_thread_writes": true
    }
  },
  "force_create_mode": null,
  "force_directory_mode": null,
  "space": 1
}

Response Fields

Same as request fields above.

1.4.5.8. DELETE /shares/samba/{id}/¶

Description

This endpoint deletes an existing Samba share identified by its unique id. Once deleted, the Samba share and its configuration will be permanently removed from the system.

Request Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	A unique integer value identifying the Samba share.

Example Request

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

Request Body Fields

This request does not require a request body. Only the id parameter in the URL path is needed.

Successful Response

Status Code: 204 No Content

Content Type: application/json

The Samba share was successfully deleted. No content is returned in the response body.

1.4.6. Spaces¶

A Space represents a logical storage area within the PixStor environment that spans one or more storage systems. Each Space is defined by key attributes such as name, location, size, data protection level, performance profile, and file share accessibility.

Spaces allow for centralized or site-specific access to storage resources and support both global and local views. Access to Spaces is governed by user roles and group permissions, enabling flexible control for administrators, users, and restricted users.

This endpoint allows interaction with Spaces for purposes such as retrieving details, listing available Spaces, or performing administrative actions depending on access level.

1.4.6.1. GET /spaces/¶

Description

The GET /spaces/ API endpoint retrieves a list of space objects from the file browser. Each space represents a storage area (mount point) that may span across multiple sites with metadata such as snapshot schedule, shares, nested shares, and more.

This endpoint supports pagination and provides detailed information per space including IDs, names, sizes, site associations, usage stats, snapshot configurations, and relationships.

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/spaces/?page=1&page_size=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": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "http://your-hub-address:8000/api/spaces/3/",
      "id": 3,
      "uuid": "6526e45d-5d5e-41c8-8c49-d68efdaab7d5",
      "name": "API_Example",
      "mountpoint": "/mmfs1/data/API_Example",
      "sites": [
        {
          "id": 1,
          "name": "siteA",
          "label": "siteA",
          "pool": "sas1",
          "usage": [0, 1099511627776]
        }
      ],
      "created": "2025-07-04T14:18:07.227156Z",
      "size": 1099511627776,
      "snapshot_schedule": {
        "id": 2,
        "frequency": "1 00:00:00",
        "time": "00:13:00",
        "duration": "7 00:00:00",
        "space": 3
      },
      "on_sites": {
        "qatest-pdevan-testplugin-siteA": {
          "name": "API_Example",
          "size": 1099511627776,
          "present": true,
          "syncing": true
        }
      },
      "immutable": false,
      "editable": true,
      "color": [111, 64, 191],
      "permission_mode": null,
      "relationships": {
        "shares": [],
        "policies": [],
        "schedules": [
          {
            "id": 3,
            "name": "Test4",
            "discovery": "recursive"
          }
        ]
      },
      "nested_shares": {
        "samba": [],
        "nfs": []
      },
      "is_ready": true
    }
  ]
}

Response Fields

Field	Description
`id`	Internal unique ID of the space.
`uuid`	Universally unique identifier.
`name`	Name of the space.
`mountpoint`	Filesystem mount path of the space.
`sites`	List of site objects the space is linked to, each with pool and usage data.
`created`	Creation timestamp of the space.
`size`	Total size in bytes.
`snapshot_schedule`	Optional object defining backup/snapshot timing and frequency.
`on_sites`	Map of site names to presence, size, and sync status of the space.
`immutable`	Boolean. Whether the space can be modified.
`editable`	Boolean. Indicates whether the space settings can be modified. This depends on the permissions of the user making the request.
`color`	RGB color array for display purposes.
`permission_mode`	(Optional) Permission configuration.
`relationships`	Contains related shares, policies, and scan schedules.
`nested_shares`	Samba and NFS shares nested within the space.
`is_ready`	Boolean. Indicates if the space is ready to be used.

1.4.6.2. POST / spaces/¶

Description

The POST /spaces/ endpoint allows you to create a new space in the system. When posting, you define metadata like: Name & mount path, Associated sites, Size, Snapshot schedule (optional), Visual settings like color, Permission handling.

Request Parameters

Name	Location	Type	Required	Description
`data`	body	object	Yes	JSON object representing the space

Example Request

curl -X 'POST' \
  'http://your-hub-address:8000/api/spaces/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "post_example",
    "mountpoint": "/mmfs2",
    "sites": [
      {
        "name": "siteA"
      }
    ],
    "size": 922337203685477,
    "snapshot_schedule": {
      "frequency": "1 00:00:00",
      "time": "00:00:00",
      "duration": "7 00:00:00"
    },
    "color": [255, 255, 255],
    "permission_mode": "chmodOnly"
  }'

Request Body Fields

Field	Type	Required	Description
`name`	string	Yes	Name of the space. Must be unique.
`mountpoint`	string	Yes	Must start with `/`. Filesystem path to mount.
`sites`	list	Yes	List of sites (by name) to associate the space with.
`size`	integer	Yes	Space size in bytes.
`snapshot_schedule`	object	Optional	Defines snapshot automation.
├─ `frequency`	string	Optional	Format like `"1 00:00:00"` (e.g., every 1 day).
├─ `time`	string	Optional	Time of day to run snapshots (e.g., `"00:00:00"`).
├─ `duration`	string	Optional	Duration to retain snapshots (e.g., `"7 00:00:00"`).
`color`	array	Optional	RGB array for UI display (e.g., `[255, 255, 255]`).
`permission_mode`	string	Optional	Permission handling mode (e.g., `"chmodOnly"`).

Successful Response

HTTP Status Code: 201 CREATED

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/spaces/7/",
  "id": 7,
  "uuid": "1d485bb0-4680-4a87-b64b-cb757bc82ccf",
  "name": "post_example",
  "mountpoint": "/mmfs2",
  "sites": [
    {
      "id": 1,
      "name": "siteA",
      "label": "siteA",
      "pool": null,
      "usage": null
    }
  ],
  "created": "2025-08-11T16:03:18.974929Z",
  "size": 922337203685477,
  "snapshot_schedule": {
    "id": 3,
    "frequency": "1 00:00:00",
    "time": "00:00:00",
    "duration": "7 00:00:00",
    "space": 7
  },
  "on_sites": {},
  "immutable": false,
  "editable": true,
  "color": [255, 255, 255],
  "permission_mode": "chmodOnly",
  "relationships": {
    "shares": [],
    "policies": [],
    "schedules": []
  },
  "nested_shares": {
    "samba": [],
    "nfs": []
  },
  "is_ready": false
}

Response Fields

Field	Description
`url`	API URL to access this space.
`id`	Unique ID of the space.
`uuid`	Universally unique ID.
`name`	Name of the created space.
`mountpoint`	Mount path starting with `/`.
`sites`	List of site objects associated with this space.
├─ `id`, `name`, `label`, etc.	Site metadata.
`created`	Timestamp when the space was created.
`size`	Size of the space in bytes.
`snapshot_schedule`	Object showing snapshot config and assigned ID.
├─ `id`, `frequency`, etc.	Snapshot metadata.
`on_sites`	Mapping of space presence/sync on each site (may be empty initially).
`immutable`	Indicates if space is read-only.
`editable`	Indicates if settings can be changed.
`color`	RGB color for UI (e.g., `[255, 255, 255]`).
`permission_mode`	Permission mode applied (e.g., `"chmodOnly"`).
`relationships`	Linked resources: shares, policies, schedules.
`nested_shares`	Nested NFS/Samba shares inside this space.
`is_ready`	Indicates if space is ready for use (typically `false` immediately after creation).

1.4.6.3. GET /spaces/{id}/¶

Description

The GET /spaces/{id}/ endpoint retrieves detailed information about a specific space, identified by its ID. It returns metadata about the space, such as: Mount path and name, Associated sites, Size and usage, Snapshot schedule, Synchronization status, Shares, policies, schedules, Readiness and permissions.

Request Parameters

Name	Location	Type	Required	Description
`id`	path	string	Yes	The numeric ID of the space to retrieve (e.g., `3`).

Example Request

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

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "url": "http://your-hub-address:8000/api/spaces/3/",
  "id": 3,
  "uuid": "6526e45d-5d5e-41c8-8c49-d68efdaab7d5",
  "name": "API_Example",
  "mountpoint": "/mmfs1/data/API_Example",
  "sites": [
    {
      "id": 1,
      "name": "siteA",
      "label": "siteA",
      "pool": "sas1",
      "usage": [0, 1099511627776]
    }
  ],
  "created": "2025-07-04T14:18:07.227156Z",
  "size": 1099511627776,
  "snapshot_schedule": {
    "id": 2,
    "frequency": "1 00:00:00",
    "time": "00:13:00",
    "duration": "7 00:00:00",
    "space": 3
  },
  "on_sites": {
    "siteA": {
      "name": "API_Example",
      "size": 1099511627776,
      "present": true,
      "syncing": true
    }
  },
  "immutable": false,
  "editable": true,
  "color": [111, 64, 191],
  "permission_mode": null,
  "relationships": {
    "shares": [],
    "policies": [],
    "schedules": [
      {
        "id": 3,
        "name": "Test4",
        "discovery": "recursive"
      }
    ]
  },
  "nested_shares": {
    "samba": [],
    "nfs": []
  },
  "is_ready": true
}

Response Fields

Field	Description
`url`	API endpoint for the specific space.
`id`	Space ID.
`uuid`	Universally unique identifier for the space.
`name`	Display name of the space.
`mountpoint`	Filesystem path to the space.
`sites`	List of site objects where this space exists.
└─ `id`, `name`, `label`	Site metadata.
└─ `pool`, `usage`	Pool name and disk usage in bytes (`[used, total]`).
`created`	Timestamp of creation (ISO 8601 format).
`size`	Total size allocated for the space.
`snapshot_schedule`	Snapshot configuration and associated space ID.
└─ `frequency`, `time`, etc.	Snapshot timing and duration settings.
`on_sites`	Dictionary of site names with current sync status.
└─ `present`, `syncing`	Booleans showing sync and availability.
`immutable`	`true` if read-only; otherwise `false`.
`editable`	Whether the space settings can be changed.
`color`	RGB color code used for UI display (e.g., `[255, 255, 255]`).
`permission_mode`	Permissions mode (can be `null`).
`relationships`	Nested relationships with other objects.
└─ `shares`, `policies`	Empty lists or linked share/policy objects.
└─ `schedules`	Discovery or snapshot schedules attached.
`nested_shares`	Samba and NFS shares created within this space, including shares from any spaces nested under it. For example, a top-level space like `mmfs1` will list all shares, as all other spaces are nested beneath it.
`is_ready`	`true` if the space is initialized and ready.

1.4.6.4. DELETE /spaces/{id}/¶

Description

Deletes a specific Space identified by its ID. This permanently removes the space from the system.

Request Parameters

Name	Description	Type	Required	Location
`id`	The unique identifier of the Space to delete	string	Yes	Path

Example Request

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

Successful Response

HTTP Status Code: 204 No Content

No response body is returned. The 204 status confirms successful deletion.

1.4.6.5. GET /spaces/{id}/files/¶

Description

Retrieves the file or directory structure inside a specific space, identified by its ID. This includes metadata such as file size, type, path, access times, and status across different sites. Useful for browsing contents within the space mount point.

Request Parameters

Name	Type	Required	Description
`id`	string	Yes	ID of the space to browse.
`path`	string	Yes	Path within the space to retrieve files from. Must start with `/`.
`site`	string	No	Specific site to target. If omitted, checks all available sites.
`details`	boolean	No	Whether to retrieve all details of child files. Default: `false`.
`restricted`	boolean	No	Whether to include restricted objects. Default: `false`.
`check_available_sites`	boolean	No	Whether to only check available sites. Default: `true`.
`raise_exception`	boolean	No	Whether to raise an exception if a timeout occurs. Default: `true`.
`custom_refresh_period`	integer	No	Custom DB cache invalidation time in seconds.
`custom_timeout`	integer	No	Custom timeout period for the operation in seconds.
`type`	string	No	Filter by item type (e.g., `file`, `directory`).
`page`	integer	No	Page number for pagination.
`page_size`	integer	No	Number of results per page. Can be `0` (no pagination), or between `20–100`.

Example Request

curl -X 'GET' \
  'http://10.201.2.224:8000/api/spaces/1/files/?path=%2Fmmfs1%2Fdata&details=false&restricted=false&check_available_sites=true&raise_exception=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

[
  {
    "url": "http://your-hub-address:8000/api/file/?path=%2Fmmfs1%2Fdata&site=qatest-pdevan-testplugin-siteB",
    "children": {
      "count": 2,
      "results": [
        {
          "site": "siteB",
          "path": "/mmfs1/data/sample_data",
          "name": "sample_data",
          "type": "directory",
          "size": 0,
          "status": "online"
        },
        {
          "site": "siteB",
          "path": "/mmfs1/data/sample_data.tgz",
          "name": "sample_data.tgz",
          "type": "file",
          "size": 0,
          "status": "online"
        }
      ]
    },
    "site": "siteB",
    "path": "/mmfs1/data",
    "name": "data",
    "type": "directory",
    "size": 512,
    "status": "online"
  },
  {
    "url": "http://your-hub-address:8000/api/file/?path=%2Fmmfs1%2Fdata&site=siteA",
    "children": {
      "count": 5,
      "results": [
        {
          "site": "siteA",
          "path": "/mmfs1/data/API_Example",
          "name": "API_Example",
          "type": "directory",
          "size": 0,
          "status": "online"
        },
        {
          "site": "siteA",
          "path": "/mmfs1/data/sample_data.tgz",
          "name": "sample_data.tgz",
          "type": "file",
          "size": 36375247,
          "status": "online",
          "disk_usage": 184025088,
          "total_files": 94,
          "data_size": 178229989
        }
      ]
    },
    "site": "siteA",
    "path": "/mmfs1/data",
    "name": "data",
    "type": "directory",
    "size": 512,
    "status": "online"
  }
]

Response Fields

Field	Type	Description
`url`	string	Link to file/directory API for this site.
`children`	object	Contains count, pagination, and results for sub-items.
`site`	string	Site this structure refers to.
`path`	string	Full path to the current folder.
`name`	string	Folder name.
`type`	string	Either `"file"` or `"directory"`.
`size`	integer	Size in bytes.
`status`	string	Status of the object, e.g., `"online"`.
`ctime` / `mtime` / `atime`	datetime	Creation, modification, and access timestamps (nullable).
`disk_usage`	integer	Disk usage in bytes (optional; present for files/directories).
`total_files`	integer	Total number of files under the directory (if available).
`data_size`	integer	Actual data size in bytes.
`deleted`	boolean	Whether it’s deleted (soft-deleted).

1.4.7. Buckets¶

1.4.7.1. GET /api/buckets/¶

Description

This API endpoint retrieves a list of storage buckets configured in the system. Buckets represent logical containers for storing data, such as files or backups, often linked to cloud storage services like Amazon S3.

You can paginate through the results using page and page_size parameters.

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/buckets/?page=1&page_size=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,
      "access_key_id": "********************",
      "secret_access_key": "********************",
      "access_key": "",
      "credentials_json": {},
      "external_targets": [],
      "name": "buckettest",
      "label": "BT 1",
      "storage_type": "AmazonS3",
      "container": "",
      "storage_account": "",
      "credentials_file": null,
      "region": "London",
      "endpoint": "s3.amazonaws.com",
      "port": 443,
      "scheme": "https",
      "migration_target_folder": "",
      "ssl_verify": true,
      "soft_deleting": false,
      "advanced_settings": {}
    }
  ]
}

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the bucket.
`access_key_id`	string (masked)	The access key ID used to authenticate with the storage service (masked for security).
`secret_access_key`	string (masked)	The secret access key for authentication (masked for security).
`access_key`	string	Azure-specific access key information, if applicable. Used in place of `access_key_id` as required by Azure (unlike S3).
`credentials_json`	object	JSON object with detailed credential info.
`external_targets`	array	List of external targets linked to this bucket.
`name`	string	Name of the bucket.
`label`	string	User-friendly label or alias for the bucket.
`storage_type`	string	Type of storage service (e.g., `"AmazonS3"`).
`container`	string	Container name or identifier (if applicable).
`storage_account`	string	Storage account identifier (if applicable).
`credentials_file`	string / null	Path to credentials file, if used.
`region`	string	Geographical region of the storage bucket (e.g., `"London"`).
`endpoint`	string	URL endpoint for the storage service (e.g., `"s3.amazonaws.com"`).
`port`	integer	Network port used to connect (typically `443` for HTTPS).
`scheme`	string	Protocol scheme, usually `"https"`.
`migration_target_folder`	string	Folder path for migration targets, if applicable.
`ssl_verify`	boolean	Whether SSL certificate verification is enabled.
`advanced_settings`	object	Additional advanced settings specific to the bucket.

1.4.7.2. POST /api/buckets/¶

Description

This API endpoint creates a new storage bucket configuration. Buckets represent storage containers in cloud services like Amazon S3, and this endpoint lets you add new ones by providing the necessary connection and authentication details.

Request Parameters

Name	Type	Required	Description
name	string	Yes	Name of the bucket. Must contain only lowercase letters, numbers, periods (.) and dashes (-).
label	string	No	User-friendly label or alias for the bucket.
storage_type	string	Yes	Type of storage service (e.g., “AmazonS3”).
container	string	No	Container name or identifier, if applicable.
access_key_id	string	Yes	Access key ID used for authenticating with the storage service.
secret_access_key	string	Yes	Secret key paired with the access key ID for authentication.
access_key	string	No	Additional access key info, if any.
storage_account	string	No	Storage account identifier, if applicable.
credentials_json	object	No	JSON object containing detailed credential information.
credentials_file	string	No	Path to a credentials file, if used.
region	string	No	Geographical region of the bucket (e.g., “us-west-1”).
endpoint	string	No	URL endpoint for the storage service (e.g., “s3.amazonaws.com”).
port	integer	No	Network port for connecting (default usually 443 for HTTPS).
scheme	string	No	Protocol scheme, usually “https”.
migration_target_folder	string	No	Folder path for migration targets, if applicable.
ssl_verify	boolean	No	Whether SSL certificate verification is enabled (default: true).
advanced_settings	object	No	Additional advanced settings specific to the bucket.

Example Request

curl -X POST \
  'http://your-hub-address:8000/api/buckets/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "bucket1",
    "label": "test 2",
    "storage_type": "AmazonS3",
    "container": "string",
    "access_key_id": "string",
    "secret_access_key": "string",
    "access_key": "string",
    "storage_account": "string",
    "credentials_json": {},
    "credentials_file": "string",
    "region": "string",
    "endpoint": "string",
    "port": 2147483647,
    "scheme": "https",
    "migration_target_folder": "string",
    "ssl_verify": true,
    "advanced_settings": {}
  }'

Successful Response

HTTP Status Code: 201 CREATED

Content-Type: application/json

Example Response

{
  "id": 2,
  "access_key_id": "********************",
  "secret_access_key": "********************",
  "access_key": "********************",
  "credentials_json": {},
  "external_targets": [],
  "name": "bucket1",
  "label": "test 2",
  "storage_type": "AmazonS3",
  "container": "string",
  "storage_account": "string",
  "credentials_file": "string",
  "region": "string",
  "endpoint": "string",
  "port": 2147483647,
  "scheme": "https",
  "migration_target_folder": "string",
  "ssl_verify": true,
  "soft_deleting": false,
  "advanced_settings": {}
}

Response Fields

Please refer to the request parameters.

1.4.7.3. GET /buckets/{id}/¶

Description

To retrieve details of a specific bucket by its unique ID.

Request Parameters

Name	Type	Required	Description
id	string	Yes	Unique identifier of the bucket.

Example Request

curl -X GET \
  'http://your-hub-address:8000/api/buckets/2/' \
  -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": 2,
  "access_key_id": "********************",
  "secret_access_key": "********************",
  "access_key": "********************",
  "credentials_json": {},
  "external_targets": [],
  "name": "bucket1",
  "label": "test 2",
  "storage_type": "AmazonS3",
  "container": "string",
  "storage_account": "string",
  "credentials_file": "string",
  "region": "string",
  "endpoint": "string",
  "port": 2147483647,
  "scheme": "https",
  "migration_target_folder": "string",
  "ssl_verify": true,
  "soft_deleting": false,
  "advanced_settings": {}
}

Response Fields

The fields returned in the response are explained at POST /api/buckets/. Please refer to those descriptions for more information about each field.

1.4.7.4. PATCH /buckets/{id}/¶

Description

Update details of an existing bucket by its unique ID.

Request Parameters

Name	Description
id (path)	The unique identifier of the bucket to update.
data (body)	JSON object containing fields to update for the bucket.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/buckets/2/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "bucket2",
    "label": "string",
    "storage_type": "AmazonS3",
    "container": "string",
    "access_key_id": "string",
    "secret_access_key": "string",
    "access_key": "string",
    "storage_account": "string",
    "credentials_json": {},
    "credentials_file": "string",
    "region": "string",
    "endpoint": "string",
    "port": 2147483647,
    "scheme": "https",
    "migration_target_folder": "string",
    "ssl_verify": true,
    "advanced_settings": {}
  }'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "id": 2,
  "access_key_id": "********************",
  "secret_access_key": "********************",
  "access_key": "********************",
  "credentials_json": {},
  "external_targets": [],
  "name": "bucket2",
  "label": "string",
  "storage_type": "AmazonS3",
  "container": "string",
  "storage_account": "string",
  "credentials_file": "string",
  "region": "string",
  "endpoint": "string",
  "port": 2147483647,
  "scheme": "https",
  "migration_target_folder": "string",
  "ssl_verify": true,
  "soft_deleting": false,
  "advanced_settings": {}
}

Response Fields

The fields returned in the response are explained at POST /api/buckets/. Please refer to those descriptions for more information about each field.

1.4.7.5. DELETE /buckets/{id}/¶

Description

Deletes a specified bucket by ID. This operation also propagates the deletion settings to external targets across all sites where the bucket is available.

It is used for complete removal of the bucket from the NGENEA Hub as well as from any connected external storage systems, based on the system’s configured deletion policies.

Request Parameters

Name	Type	Required	Description
id	string	Yes	The unique identifier of the bucket.

Example Request

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

Successful Response

HTTP Status Code: 204 No Content

Content-Type: application/json

No content is returned in the response body upon successful deletion.

Note

This operation is irreversible, once deleted, the bucket and its settings are removed from all locations.

Ensure that the bucket is not in use before calling this endpoint.

Deletion is subject to permission and may fail if the bucket is protected or referenced by other resources.

1.4.8. Storage Pools¶

A storage pool is a logical collection of physical storage resources, such as hard drives or SSDs, grouped together to simplify management and optimize the usage of available storage.

In systems like Pixstor (GPFS), storage pools allow administrators to treat multiple devices as a single unit, enabling better scalability, load balancing, and efficient data management. These pools are essential for organizing and managing file systems across distributed environments.

In Ngenea Hub, storage pool metadata, including capacity and health status, is regularly refreshed to ensure accurate tracking and monitoring. By using storage pools, administrators can easily manage space, track storage utilization, and ensure system performance remains optimal.

1.4.8.1. GET /storagepools/¶

Description

The GET /storagepools/ API retrieves a list of storage pools within the Ngenea Hub system, showing details like the pool’s capacity, usage, and the site it belongs to.

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/storagepools/?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": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "sas1",
      "filesystem": "mmfs1",
      "site": 1,
      "capacity": 89120571392,
      "used_space": 3070230528,
      "free_space": 86050340864,
      "is_default": true
    },
    {
      "name": "sas1",
      "filesystem": "mmfs1",
      "site": 2,
      "capacity": 89120571392,
      "used_space": 2944401408,
      "free_space": 86176169984,
      "is_default": true
    }
  ]
}

Response Fields

Field	Description	Example
count	The total number of storage pools available.	2
next	The URL for the next page of results, if available. `null` if no more pages.	null
previous	The URL for the previous page of results, if available. `null` if first page.	null
results	An array containing details about each storage pool.

Each entry in results contains the following fields:

Field	Description	Example
name	The name of the storage pool.	“sas1”
filesystem	The file system associated with the pool.	“mmfs1”
site	The site ID where the storage pool is located.	1
capacity	The total capacity of the storage pool in bytes.	89120571392
used_space	The amount of space currently used in the pool (in bytes).	3070230528
free_space	The remaining space available in the pool (in bytes).	86050340864
is_default	A boolean indicating if this is the default storage pool.	true

1.4.8.2. GET /storagepools/{id}/¶

Description

This endpoint is used to retrieve detailed information about a specific storage pool identified by the ‘ID’ parameter. This is a more focused API call compared to the previous one, as it allows you to get data for a particular storage pool rather than a list of all storage pools.

Request Parameters

Field	Description	Example
id	The unique identifier (ID) for the specific storage pool to retrieve.	2

Example Request

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

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "name": "sas1",
  "filesystem": "mmfs1",
  "site": 2,
  "capacity": 89120571392,
  "used_space": 2961178624,
  "free_space": 86159392768,
  "is_default": true
}

Response Fields

Please refer to the response fields under GET/storagepools/.

Note

In the example response:

The storage pool is named “sas1” and uses the “mmfs1” filesystem.
It is located at site 2.
The total capacity of the pool is approximately 89 GB, with around 3 GB used and 86 GB remaining.
The pool is marked as the default pool (true).