1.5. API Endpoints - Configuration & System Settings¶

1.5.1. Configurations¶

1.5.1.1. GET /configurations/¶

Description

This endpoint retrieves the current runtime configuration settings of the Ngenea Hub.

These are dynamic configurations, they can be read (and potentially modified through other endpoints , explained below) without requiring a restart of the Hub. This contrasts with the static configuration values that are set during the initial Hub setup, which typically require a restart to take effect.

These configuration values control various operational aspects of the Ngenea Hub, such as search behavior, job lifecycle, timeouts, analytics, and user management settings.

Example Request

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

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "jobs_ttl": 90,
  "search_backend": "pixstor_search",
  "search_max_results": 200,
  "search_result_ttl": 7,
  "snapshot_create_delete_retry_timeout": 1000,
  "stat_timeout": 10,
  "stat_refresh_period": 30,
  "task_invalidation_timeout": 3600,
  "snapdiff_stream_timeout": 10,
  "force_local_managed_users": false,
  "custom_statistics_tasks": [],
  "analytics_timeout": 10,
  "maximum_external_results": 100,
  "node_health_last_heartbeat_interval": 120,
  "initial_uid": 100000,
  "initial_gid": 100000,
  "schedules_enabled": true,
  "salt_task_timeout": 60
}

Response Fields

Field	Type	Description
`jobs_ttl`	integer	How long job details should be stored after job completion, in days.
`search_backend`	string	Backend to use when performing searches. Currently supported backends: `analytics`, `pixstor_search`.
`search_max_results`	integer	Maximum number of search results to fetch from the search backend, per site. Some backends may have a hard limit of 10,000 results.
`search_result_ttl`	integer	How long search results should be stored, in days.
`snapshot_create_delete_retry_timeout`	integer	Time in seconds after which workers will give up retrying snapshot create and delete operations. Set to 0 to disable retries.
`stat_timeout`	integer	How long to wait for results from the `/api/file/` endpoint, in seconds.
`stat_refresh_period`	integer	How long a file’s details will be retained as a cache within the file browser, in seconds.
`task_invalidation_timeout`	integer	Idle timeout (in minutes) when waiting for delete and move tasks to complete during snapdiff workflows.
`snapdiff_stream_timeout`	integer	Timeout in seconds for snapdiff stream operations.
`force_local_managed_users`	boolean	Allows local NAS users to be managed on AD-joined sites.
`custom_statistics_tasks`	array	A list of custom tasks that add their reported file count to the job total, regardless of when they’re executed in a workflow.
`analytics_timeout`	integer	How long to wait for results from search operations when using the analytics backend, in seconds.
`maximum_external_results`	integer	Maximum number of items to retrieve per page from an external target scan.
`node_health_last_heartbeat_interval`	integer	Maximum allowed time (in seconds) between the last recorded heartbeat and now for a node to be considered online.
`initial_uid`	integer	Minimum UID value for NAS users that can be configured.
`initial_gid`	integer	Minimum GID value for NAS groups that can be configured.
`schedules_enabled`	boolean	Whether automated tasks (Policies and Scheduled Workflows) are enabled.
`salt_task_timeout`	integer	How long to wait for settings tasks to return results, in seconds.

1.5.1.2. PATCH /configurations/¶

Description

Updates one or more runtime configuration settings on the NGENEA Hub.

These settings are applied without requiring a restart of the Hub. They influence the behavior of search, task execution, user management, and other key services.

This endpoint allows partial updates, only the fields provided in the request body are modified.

Request Parameters

Name	Type	Required	Location	Description
`data`	object	Yes	Body	A JSON object with one or more configuration fields to update.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/configurations/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <REDACTED>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobs_ttl": 10,
    "search_backend": "analytics",
    "search_max_results": 100,
    "search_result_ttl": 5,
    "snapshot_create_delete_retry_timeout": 1000,
    "stat_timeout": 10,
    "stat_refresh_period": 10,
    "task_invalidation_timeout": 360,
    "snapdiff_stream_timeout": 2147483647,
    "force_local_managed_users": true,
    "custom_statistics_tasks": [
      "dynamo.custom.get_all_pngs"
    ],
    "analytics_timeout": 2147483647,
    "maximum_external_results": 2147483647,
    "node_health_last_heartbeat_interval": 2147483647,
    "initial_uid": 100000,
    "initial_gid": 100000,
    "schedules_enabled": true,
    "salt_task_timeout": 0
}'

Request Body Fields

Field	Value	Description
`jobs_ttl`	10	Time-to-live for job records (in days).
`search_backend`	“analytics”	The backend engine used for search operations.
`search_max_results`	100	Maximum number of results returned per search query.
`search_result_ttl`	5	Time-to-live (in days) for cached search results.
`snapshot_create_delete_retry_timeout`	1000	Timeout in milliseconds before retrying snapshot create/delete operations.
`stat_timeout`	10	Timeout in seconds for file stat operations.
`stat_refresh_period`	10	Refresh interval (in seconds) for filesystem statistics.
`task_invalidation_timeout`	360	Time in seconds before a background task becomes invalid or stale.
`snapdiff_stream_timeout`	2147483647	Timeout in seconds for snapdiff stream operations (effectively no timeout).
`force_local_managed_users`	true	Enforces user management to be handled locally rather than externally.
`custom_statistics_tasks`	[“dynamo.custom.get_all_pngs”]	A list of custom tasks for advanced statistics processing.
`analytics_timeout`	2147483647	Timeout in seconds for analytics operations (effectively no timeout).
`maximum_external_results`	2147483647	Max number of results returned by external search sources (effectively no limit).
`node_health_last_heartbeat_interval`	2147483647	Interval in seconds for checking the last heartbeat of nodes (effectively no timeout).
`initial_uid`	100000	Starting UID for system-generated users.
`initial_gid`	100000	Starting GID for system-generated groups.
`schedules_enabled`	true	Whether scheduled tasks are enabled on the Hub.
`salt_task_timeout`	0	Timeout in seconds for tasks handled by SaltStack orchestration (0 means no timeout).

Note

All the data provided above is for example purposes only.

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "jobs_ttl": 10,
  "search_backend": "analytics",
  "search_max_results": 100,
  "search_result_ttl": 5,
  "snapshot_create_delete_retry_timeout": 1000,
  "stat_timeout": 10,
  "stat_refresh_period": 10,
  "task_invalidation_timeout": 360,
  "snapdiff_stream_timeout": 2147483647,
  "force_local_managed_users": true,
  "custom_statistics_tasks": [
    "dynamo.custom.get_all_pngs"
  ],
  "analytics_timeout": 2147483647,
  "maximum_external_results": 2147483647,
  "node_health_last_heartbeat_interval": 2147483647,
  "initial_uid": 100000,
  "initial_gid": 100000,
  "schedules_enabled": true,
  "salt_task_timeout": 0
}

Response Fields

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

1.5.2. Features - Feature Flag¶

Feature flags are configuration settings used to enable or disable specific functionality within an application without requiring code changes or redeployments. They are especially useful for testing new or experimental features in a controlled manner.

In Ngenea Hub, feature flags allow administrators to preview features that may still be under development or evaluation.

By default, all preview features are disabled to ensure system stability. However, they can be selectively enabled for testing or early access. It’s important to understand that enabling these features comes with the risk of encountering incomplete or unstable behavior.

To interact with feature flags, you can use the ngclient command-line tool or make requests via the Ngenea Hub REST API.

To turn features on or off using the command line, see the section: Via ngclient command-line tool
To see the results using Swagger, see below.

1.5.2.1. GET /features/¶

Description

This API endpoint is used to list all available feature flags in the system. You can see which features are currently available and whether they are enabled or disabled.

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/features/?page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <api-key>'

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

Response Fields

Field	Type	Description
`count`	integer	Total number of available features.
`next`	string	URL to the next page of results, or `null` if this is the last page.
`previous`	string	URL to the previous page of results, or `null` if this is the first page.
`results`	array	List of feature objects (name, description, and enabled status). Empty if no features are available.

There are no feature flags currently available.

1.5.2.2. GET /features/{name}/¶

Description

This endpoint is used to retrieve details of a specific feature flag by its name. For example, to check the status of a feature named searchui.

Request Parameters

Name	Type	In	Description
`name`	string	path	(Required) The name of the feature to look up.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/features/searchui/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <api_key>'

Response

HTTP Status Code: 404 Not Found

Example Response

{
  "detail": "No Feature matches the given query."
}

For example, we used searchui in the request. When the feature flag is available, this will return its details such as name, description, and whether it is enabled.

1.5.2.3. PATCH /features/{name}/¶

Description

This endpoint is used to enable or disable a specific feature flag by name. You send a request with {"enabled": true} to turn the feature on, or {"enabled": false} to turn it off.

As there are no feature flags currently available, we are using searchui as an example only in this request.

Request Parameters

Name	Type	In	Description
`name`	string	path	(Required) The name of the feature flag to update.
`data`	object	body	(Required) JSON object with the `enabled` field set to `true` or `false`.

Example Request

curl -X 'PATCH' \
  'http://your-hub-address:8000/api/features/searchui/' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key ************' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true
}'

Successful Response

HTTP Status Code: 404 Not Found

Example Response

{
  "detail": "No Feature matches the given query."
}

1.5.3. Nodes¶

1.5.3.1. GET /nodes/¶

Description

This API endpoint retrieves a list of worker nodes that are registered with the Ngenea Server. Each node represents a system running the ngenea-worker component. This endpoint supports pagination, and each node includes details such as its name, site, status (online/offline), and last heartbeat timestamp.

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/nodes/?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://<server-ip>:<port>/api/nodes/1/",
      "id": 1,
      "name": "node-siteA-1",
      "site": "siteA",
      "online": true,
      "has_default_queue": true,
      "last_heartbeat": "2025-06-30T13:04:44.758754Z"
    },
    {
      "url": "http://<server-ip>:<port>/api/nodes/2/",
      "id": 2,
      "name": "node-siteB-1",
      "site": "siteB",
      "online": true,
      "has_default_queue": true,
      "last_heartbeat": "2025-06-30T13:04:44.845662Z"
    }
  ]
}

Response Fields

Field	Type	Description
`count`	integer	Total number of nodes in the system.
`next`	string or null	URL to the next page of results, if any.
`previous`	string or null	URL to the previous page of results, if any.
`results`	array	List of node objects. Each object includes the following fields:
→ `url`	string	API URL for the specific node.
→ `id`	integer	Unique ID of the node.
→ `name`	string	Name of the node.
→ `site`	string	Site or cluster the node belongs to.
→ `online`	boolean	Indicates if the node is currently online.
→ `has_default_queue`	boolean	Indicates if the node has a default task queue assigned.
→ `last_heartbeat`	string (timestamp)	Timestamp of the last time the node checked in (ISO 8601 format).

GET /nodes/{id}/

Description

This API endpoint retrieves detailed information for a specific worker node identified by its unique ‘ID’. This is useful for monitoring or managing individual nodes.

Request Parameters

Name	Type	Location	Required	Description
`id`	string	path	Yes	The unique identifier of the node you want to retrieve.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/nodes/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://<server-ip>:<port>/api/nodes/2/",
  "id": 2,
  "name": "node-siteB-1",
  "site": "siteB",
  "online": true,
  "has_default_queue": true,
  "last_heartbeat": "2025-06-30T13:05:00.863706Z"
}

Response Fields

Please refer to response fields under GET /nodes/.

1.5.3.2. DELETE /nodes/{id}/¶

Description

Deletes a specific worker node from the Ngenea Server by its ID. Once deleted, the node will no longer be registered until it sends another heartbeat.

This can be useful if a node has been intentionally taken offline and you no longer want the hub to report on it, otherwise, the site health status may show as not OK.

Request Parameters

Name	Type	Location	Required	Description
`id`	string	path	Yes	The unique identifier of the node you want to retrieve.

Example Request

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

Successful Response

HTTP Status Code: 204 No Content

Indicates the node was successfully deleted. There is no response body when deletion is successful.

1.5.4. Settings Tasks¶

What is a task ?

In Ngenea hub, a task is a defined unit of work that performs a specific operation on a set of files or paths.

It is typically implemented as a Python function or method that receives a standardized set of arguments, such as the job ID (jobid), a list of paths to process (paths), and optional keyword arguments.

The task processes the inputs and returns a structured payload that describes the result, including which files were processed, skipped, failed, or aborted.

Tasks follow a strict input and output format to ensure compatibility within the Ngenea ecosystem.

Why is a Task Needed?

Tasks are essential because they encapsulate discrete pieces of logic that can be reused and composed into larger workflows. Each task is responsible for carrying out a single step in a larger data processing pipeline, such as migrating data, deleting files, analyzing metadata, or verifying integrity.

How is a Task Related to a Job?

A job in Ngenea is a higher-level structure that coordinates and tracks the execution of a workflow, a series of tasks. When a job is initiated, it orchestrates the execution of its constituent tasks in a defined sequence. Each task within the job receives the job’s ID, so all task results can be traced back to the originating job. The job manages the state, progress, and outcome of the entire workflow, while tasks handle the execution of individual steps.

In essence, tasks are the functional building blocks of jobs. A job cannot execute without tasks, and tasks are only meaningful when they are executed within the context of a job. Together, they form the backbone of Ngenea’s data processing capabilities, allowing for flexible, trackable, and customizable workflows.

Learn More.

1.5.4.1. GET /settingstasks/¶

Description

This API endpoint retrieves a list of tasks associated with a specific job. It supports filtering by task state and task type, as well as pagination. It is typically used to monitor the status of tasks within a job.

Request Parameters

Name	Type	Required	Description
`job_id`	integer	Yes	The ID of the job whose tasks should be retrieved. Must be ≥ 1.
`page`	integer	No	Page number in the paginated result set. Defaults to 1.
`page_size`	integer	No	Number of results per page. Range: 20–100. Use 0 to disable pagination.
`tasktype`	string (max 50)	No	Filters tasks by their type (e.g., `dynamo.tasks.set_config_and_apply`).
`state`	array[string]	No	Filters tasks by their state. Accepted values include `SUCCESS`, `ERROR`, `PENDING`, etc.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/settingstasks/?page=1&state=SUCCESS&job_id=84' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key your-api-key'

Request Body Fields

Field	Type	Description
`count`	integer	Total number of tasks matching the query.
`next`	string or null	URL to the next page of results, if any.
`previous`	string or null	URL to the previous page of results, if any.
`results`	array of objects	List of task objects. Each represents one task.
`stats`	object	Summary statistics about the returned tasks, broken down by state and tasktype.

Task Object (Inside results)

Field	Type	Description
`url`	string	URL of the individual task resource.
`id`	integer	Unique ID of the task.
`task_id`	string	UUID representing the task instance.
`tasktype`	string	Type of the task (function name).
`state`	string	Current state of the task (e.g., SUCCESS).
`job`	integer	Job ID the task belongs to.
`site`	string	Site where the task ran.
`started`	string	Start time in UTC (ISO 8601 datetime format).

Successful Response

HTTP Status Code: 200 OK

Content-Type: application/json

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "http://your-hub-address:8000/api/settingstasks/78/",
      "id": 78,
      "task_id": "b8bc9471-ea1f-47ec-bea7-75230452e7c5",
      "tasktype": "dynamo.tasks.set_config_and_apply",
      "state": "SUCCESS",
      "job": 84,
      "site": "siteA",
      "started": "2025-06-25T12:00:02.108785Z"
    }
  ],
  "stats": {
    "state": {
      "SUCCESS": 1
    },
    "tasktype": {
      "dynamo.tasks.set_config_and_apply": 1
    }
  }
}

Response Fields

Please refer to the resquest body fields.

1.5.4.2. GET /settingstasks/{id}/¶

Description

This API endpoint retrieves detailed information about a specific task by its ‘ID’.

Request Parameters

Name	Type	Location	Required	Description
`id`	string	path	Yes	The unique identifier of the no

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/settingstasks/78/' \
  -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/settingstasks/78/",
  "id": 78,
  "task_id": "b8bc9471-ea1f-47ec-bea7-75230452e7c5",
  "tasktype": "dynamo.tasks.set_config_and_apply",
  "state": "SUCCESS",
  "started": "2025-06-25T12:00:02.108785Z",
  "completed": "2025-06-25T12:01:17.021510Z",
  "runtime": 74.912725,
  "job": 84,
  "site": "siteA",
  "request": {
    "values": {
      "ngeneahsm_targets:mmfs1-test2:Port": 443,
      "ngeneahsm_targets:mmfs1-test2:Bucket": "test2",
      "ngeneahsm_targets:mmfs1-test2:Region": "London",
      "ngeneahsm_targets:mmfs1-test2:Scheme": "https",
      "ngeneahsm_targets:mmfs1-test2:enabled": true,
      "ngeneahsm_targets:mmfs1-test2:Endpoint": "s3.amazonaws.com",
      "ngeneahsm_targets:Test_Space-test2:Port": 443,
      "ngeneahsm_targets:mmfs1-test2:SSLVerify": true,
      "ngeneahsm_targets:Test_Space-test2:Bucket": "test2",
      "ngeneahsm_targets:Test_Space-test2:Region": "London",
      "ngeneahsm_targets:Test_Space-test2:Scheme": "https",
      "ngeneahsm_targets:mmfs1-test2:StorageType": "AmazonS3",
      "ngeneahsm_targets:Test_Space-test2:enabled": true,
      "ngeneahsm_targets:Test_Space-test2:Endpoint": "s3.amazonaws.com",
      "ngeneahsm_targets:Test_Space-test2:SSLVerify": true,
      "ngeneahsm_targets:mmfs1-test2:DeleteOnRecall": false
      // ... more values ...
    },
    "timeout": 0,
    "encrypted": [
      "ngeneahsm_targets:mmfs1-test2:AccessKeyId",
      "ngeneahsm_targets:mmfs1-test2:SecretAccessKey",
      "ngeneahsm_targets:Test_Space-test2:AccessKeyId",
      "ngeneahsm_targets:Test_Target-buckettest:AccessKeyId",
      "ngeneahsm_targets:Test_Space-test2:SecretAccessKey",
      "ngeneahsm_targets:Test_Target-buckettest:SecretAccessKey"
    ],
    "multi_update": false
  },
  "results": {
    "value": {
      "ngeneahsm_targets:mmfs1-test2:Port": {
        "value": 443,
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:Port"
      },
      "ngeneahsm_targets:mmfs1-test2:Bucket": {
        "value": "test2",
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:Bucket"
      },
      "ngeneahsm_targets:mmfs1-test2:Region": {
        "value": "London",
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:Region"
      },
      "ngeneahsm_targets:mmfs1-test2:Scheme": {
        "value": "https",
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:Scheme"
      },
      "ngeneahsm_targets:mmfs1-test2:enabled": {
        "value": true,
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:enabled"
      },
      "ngeneahsm_targets:mmfs1-test2:Endpoint": {
        "value": "s3.amazonaws.com",
        "is_set": true,
        "schema_key": "ngeneahsm_targets:mmfs1-test2:Endpoint"
      }
      // ... more results ...
    },
    "status": "succeeded",
    "apply_output": {
      "siteA-1.pixstor": "succeeded"
    }
  },
  "friendly_name": "Example Friendly Name"
}

Note

This API response represents the details of a completed task that configures and applies multiple Amazon S3 storage settings to a specific site in the system. The task executed successfully, confirming that the configuration parameters (including security credentials, bucket names, endpoints, and access settings) were applied without errors to the target site siteA. The response provides a detailed snapshot of both the requested settings and the resulting state, useful for auditing and verification purposes.

Response Fields

Field	Type	Description
`url`	string	The API URL for this specific task resource.
`id`	integer	Unique identifier of the task instance (database ID).
`task_id`	string	UUID representing the specific task instance.
`state`	string	Current status of the task, e.g., `"SUCCESS"`, `"ERROR"`.
`started`	string	Timestamp when the task started (ISO 8601 UTC datetime).
`completed`	string	Timestamp when the task completed (ISO 8601 UTC datetime).
`runtime`	float	Duration of the task in seconds (completion time - start time).
`results`	object	Detailed output of the task after completion, including values, status, and apply output summary.
`friendly_name`	string	A user-friendly descriptive name for the task (optional).

1.5.5. Tags¶

A Tag is a case-sensitive, user-defined keyword used to categorize and organize assets. Tags help group related assets together, making it easier to manage and retrieve them within your environment.

Tags are a core part of the Search functionality, powered by PixStor Search. Once applied, Tags allow users to filter and find assets more efficiently using the Search interface. Tags are indexed asynchronously, so there may be a short delay before newly applied Tags are searchable.

While there is no dedicated endpoint to create or assign Tags directly, Tags can be retrieved using the GET /tags endpoint. To apply Tags to assets, use the PATCH /search/metadata endpoint to update asset metadata with the desired Tags.

For more details, refer to the Search documentation and Search API reference to learn how Tags integrate with your search workflows.

1.5.5.1. GET /tags/¶

Description

This API endpoint allows clients to retrieve a list of tags. You can optionally filter the results by passing a substring to match tag names.

Request Parameters

Name	Type	Description	Required	Constraints
filter	string	Substring that returned tags must contain (query)	No	Minimum length: 1

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/tags/?filter=ex' \
  -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": "example"
  },
  {
    "name": "three"
  },
  {
    "name": "two"
  },
  {
    "name": "one"
  }
]

Response Fields

Field	Type	Description
name	string	Name of the tag

1.5.6. Servers¶

Servers are integral components of a site, and they work together to handle different data operations, including file storage, retrieval, and data synchronization. They also facilitate network interactions and ensure that data is accessible to users or other systems within the network.

Servers are closely linked to sites, as they are the primary units within a site that enable the actual storage and management of data, with configurations being centrally managed through Ngenea Hub for optimal performance and monitoring.

No servers will be listed unless the gateway role is enabled on the site’s Pixstor system.

To enable the gateway role, run: pixstor-enablefeature gateway

After enabling, it may take some time for CTDB servers to appear in the Ngenea Hub. To force detection and synchronization, you can run the following Salt commands:

salt '' saltutil.sync_grains
salt '' mine.update
ngclient sites refresh

These steps ensure the server data is refreshed and made available in Hub for further configuration of network interfaces.

1.5.6.1. GET /servers/¶

Description

The GET /servers/ endpoint retrieves a list of servers associated with configured sites. Each server entry includes its name, the associated site ID, and a list of network interfaces available on that server. This data is useful for viewing and managing the network configuration of servers within a 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/servers/?page=1&page_size=20' \
  -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": [
    {
      "name": "siteA-1.pixstor",
      "site": 1,
      "list_of_interfaces": [
        "ens5",
        "ens6",
        "dummy0",
        "br-7cec54d64949",
        "br-88ea4b8e41a3",
        "br-02ebdc5f687f",
        "br-d15e54973410",
        "br-07214fcfa2b6",
        "br-bed322cf088d"
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`count`	integer	Total number of server records available
`next`	string / null	URL to next page of results, or null if no next page
`previous`	string / null	URL to previous page of results, or null if on first page
`results`	array of objects	List of server objects

Server Object (Inside results)

Field	Type	Description
`name`	string	Fully qualified name of the server
`site`	integer	ID of the site the server belongs to
`list_of_interfaces`	array of strings	Network interfaces available on the server

1.5.6.2. GET /servers/{id}/¶

Description

Retrieves detailed information about a specific server by its unique ID, including the server’s name, associated site, and list of network interfaces.

Request Parameters

Name	Type	Location	Required	Description
`id`	string	path	Yes	The unique identifier of the node you want to retrieve.

Example Request

curl -X 'GET' \
  'http://your-hub-address:8000/api/servers/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": "siteA-1.pixstor",
  "site": 1,
  "list_of_interfaces": [
    "ens5",
    "ens6",
    "dummy0",
    "br-7cec54d64949",
    "br-88ea4b8e41a3",
    "br-02ebdc5f687f",
    "br-d15e54973410",
    "br-07214fcfa2b6",
    "br-bed322cf088d"
  ]
}

Response Fields

Please refer to Response Fields under GET /servers/.