NVIDIA SHARP REST API | UFM REST API Guide

SHARP Reservations APIs

Important Notes:

SHARPv2 must be running (enable_SHARP = true) and the NVIDIA Scalable Hierarchical Aggregation and Reduction Protocol (SHARP)™ allocation parameter must be enabled (enable_SHARP_alloction = true) for this API to trigger resource (GUID) allocations and deallocations within SHARP.
The current operation: By default, SHARP operates with automatic reservation management by PKeys (reservation_auto_by_pkeys is TRUE). Once the PKey is defined by the SM, SHARP synchronizes the changes made according to the PKey definitions - it automatically creates, updates, and deletes reservations.
As of April 2026 UFM release, the REST APIs for creating, deleting, and updating reservations will become unavailable. For the current release, to continue working with the create, delete, and update APIs, the reservation_auto_by_pkeys parameter in sharp_am.cfg must be set to FALSE.
The Get Reservation REST API remains available in all modes and can be used to query existing reservations.

NVIDIA SHARP reservation REST APIs support the following operations:

Get All Reservations

Description – Retrieves all SHARP reservations
Request URL – GET /ufmRest/app/sharp/allocate_resources
Request Content-Type – Application/json

Response

{
   "anas1":{
      "pkey":"0x12",
      "guids":["0x248a0703008a850a", "0x248a0703008a850b"]
   },
   "anas2":{
      "pkey":"0x12",
      "guids": ["0xf452140300383a01", "0xf452140300383a02"]
   }
}

Status Codes
- 200 – OK
- 400 – BAD_REQUEST

Get Specific SHARP Reservation

Description – Gets specific SHARP reservation by app_id
Request URL – GET /ufmRest/app/sharp/allocate_resources/<app_id>
Request Content Type – Application/json
Status Codes200 – OK400 – BAD_REQUEST404 – NOT_FOUND

{
   "anas1":{
      "pkey": "0x12",
      "guids": ["0x248a0703008a850a", "0x248a0703008a850b"]
   }
}

Create a New SHARP Reservation

The following API is replacing the deprecated SHARP API presented in earlier versions of this UFM Enterprise REST API Guide.

Description – Creates a new SHARP reservation. By default, the SHARP blocking API is called, which entails sending the reservation request to SHARP and awaiting the response (success or fail). To revert to the previous behavior of using the non-blocking API, set the "blocking" parameter in the API to false. If the partial allocation parameter is set to false, the SHARP allocation request will not succeed in the event that even a single node is absent in the fabric. By default, this parameter is set to true.
Example of a false partial allocation: Request URL – POST /ufmRest/app/sharp/resources?partially_alloc=false
Example of calling a non-blocking API: Request URL – POST /ufmRest/app/sharp/resources?blocking=false
Request Content-Type – Application/json
Status Codes202 – ACCEPTED (All nodes were added successfully to created allocation)206 – PARTIAL (Not all nodes were added to created allocation because they are not found in the fabric)200 - OK (All nodes were added successfully to the created allocation and the SHARP blocking API is called)400 – BAD_REQUEST

Request Data

Name	Value	Default	Description	Mandatory/Optional
App_id	String	None	"0x7fff" (This is the default management pkey) Application id. It is also the identifier of this nodes allocation	Mandatory
App_resources_limit	Integer	-1	Application resources limitation	Optional
Hosts_names	String	None	A string of hosts names separated by a comma, to be added to sharp allocation. Example: "r-ufm77,r-ufm51"	Optional
Port_guids	list	None	List of ports guids Example: ["f452140300383a01", "f452140300383a02"]	Optional
pkey	Hexadecimal string between "0x0001"-"0x7ffe" exclusive	"0x7fff" (This is the default management pkey)	Created network PKey to be used by Sharp	Optional

Examples:

Create SHARP allocation by sending hosts_names:

{
"app_id":"99",
"hosts_names":"r-ufm51,r-ufm55", 
"pkey":"0x12",
"app_resources_limit": -1
}

Create SHARP allocation by sending port_guids:

{
"app_id":"99",
"port_guids": ["f452140300383a01", "f452140300383a02"],
"pkey":"0x12",
"app_resources_limit": -1
}

Delete SHARP Reservation

The following API is replacing the deprecated SHARP API presented in earlier versions of the UFM Enterprise REST API Guide.

Description - Deletes SHARP Allocation. By default, the SHARP blocking API is called to delete SHARP reservation.
Example of calling delete allocation using SHARP blocking API: Request URL - DELETE /ufmRest/app/sharp/resources/<app_id>
Example of calling delete allocation using SHARP non-blocking API: Request URL - DELETE /ufmRest/app/sharp/resources/<app_id>?blocking=false
Request Content-Type – Application/json
Status Codes204 – NO CONTENT400 – BAD_REQUEST

Update SHARP Reservation

The following API is replacing the deprecated SHARP API presented in earlier versions of this UFM Enterprise REST API Guide.

Description – Updates SHARP Allocation. By default, the update SHARP blocking API is called, which entails sending the update reservation request to SHARP and awaiting the response (success or fail). To revert to the previous behavior of using the non-blocking API, set the "blocking" parameter in the API to false. If the partial allocation parameter is set to false, the SHARP allocation request will not succeed in the event that even a single node is absent in the fabric. By default, this parameter is set to true.
Example of a false partial allocation: Request URL – PUT /ufmRest/app/sharp/resources/<app_id>?partially_alloc=false
Example of calling a non-blocking API: Request URL – PUT /ufmRest/app/sharp/resources<app_id>?blocking=false
Request Content-Type – Application/json
Status Codes202 – ACCEPTED (All nodes were updated successfully to SHARP allocation)206 – PARTIAL (Not all nodes were updated to SHARP allocation because they are not found in the fabric)200 - OK (All nodes were updated successfully to the SHARP allocation and the SHARP blocking API is called)400 – BAD_REQUEST
Body Examples:Update SHARP allocation by sending hosts_names: {    "hosts_names":"r-ufm51,r-ufm77" } Update SHARP allocation by sending port_guids: {    "port_guids":["f452140300383a01", "f452140300383a02"] }

Update SHARP Reservation by Delta

Description – Updates the SHARP Allocation API to allow updating an existing allocation by specifying only the added and removed RDMA NIC GUIDs, rather than requiring the full list.

Add GUIDs to SHARP Allocation API

Description: Add port_guids to update the existing SHARP allocation. This API will take in a list of RDMA NIC GUIDs and add them to a specified SHARP reservation.
Method: PUT
URL: /ufmRest/app/sharp/resources/<app_id>/add_guids

Request Body Example:

{
 "port_guids”: ["98039b0300860ace","98039b0300860acf","b8599f03000a7768"] 
}

Remove GUIDs from SHARP Allocation API

Description: Remove port_guids to update the existing SHARP allocation. This API will take in a list of RDMA NIC GUIDs and remove them from a specified SHARP reservation.
Method: PUT
URL:

/ufmRest/app/sharp/resources/<app_id>/remove_guids

Request Body Example:

{
"port_guids": ["f452140300383a01", "f452140300383a02"]
}

Get All Sharp Reservations API

Description: Returns a dictionary of all SHARP reservation and partition keys without the member GUIDs info
Method: GET
URL:

ufmRest/app/sharp/allocate_resources?with_guids=false

Response:

{
"10": {"pkey": "0x12"},
"99":{"pkey": "0x13"}
}

SHARP Jobs APIs

The SHARP jobs REST API provides methods on obtaining information on SHARP jobs and support the following operations:

Get All SHARP Jobs

Description – Retrieves all active SHARP jobs.
Request URL – GET /ufmRest/app/sharp/resources/jobs
Request Content Type – Application/json
Status Codes200 – OK

Response

{
   "99:58":{
      "job_id":58,
      "num_guids":1,
      "num_rails":1,
      "trees":{
         "0":{
            "tree_id":0,
            "type":"LLT",
            "ANs":{
               "0x33333":{
                  "description":"sw3",
                  "lid":23,
                  "rank":1,
                  "guid":"0x33333",
                  "parent_guid":null,
                  "child_guids":null,
                  "hca_guids":[
                     "0x78395179",
                     "0x78395178"
                  ]
               }
            }
         }
      },
      "reservation_key":"99"
   },
   "99:74":{
      "job_id":74,
      "num_guids":1,
      "num_rails":1,
      "trees":{
         "0":{
            "tree_id":0,
            "type":"LLT",
            "ANs":{
               "0x33333":{
                  "description":"sw3",
                  "lid":23,
                  "rank":1,
                  "guid":"0x33333",
                  "parent_guid":null,
                  "child_guids":null,
                  "hca_guids":[
                     "0x78395179",
                     "0x78395178"
                  ]
               }
            },
            "reservation_key":"99"
         }
      }
   }
}

Get a Specific SHARP Job

Description – Retrieves specific active SHARP jobs with specific a reservation_id
Request URL – GET /ufmRest/app/sharp/resources/jobs/<job_id>?reservation_id=<reservation_id>
Request Content Type – Application/json
Status Codes 200 – OK404 – NOT_FOUND

Response

{
   "99:58":{
      "job_id":58,
      "num_guids":1,
      "num_rails":1,
      "trees":{
         "0":{
            "tree_id":0,
            "type":"LLT",
            "ANs":{
               "0x33333":{
                  "description":"sw3",
                  "lid":23,
                  "rank":1,
                  "guid":"0x33333",
                  "parent_guid":null,
                  "child_guids":null,
                  "hca_guids":[
                     "0x78395179",
                     "0x78395178"
                  ]
               }
            }
         }
      },
      "reservation_key":"99"
   }
}

Get All SHARP Non-Blocking Jobs

Description – Retrieves all active SHARP jobs using non blocking SHARP API
Request URL – GET /ufmRest/app/sharp/resources/jobs_nb
Request Content Type – Application/json
Status Codes 200 – OK

Response – the HTTP response location header contains a URL with job ID created for running the action.
Example:

{
   "ID":"1",
   "Status":"Completed",
   "Progress":100,
   "Description":"Get sharp jobs",
   "Created":"2023-05-03 09:48:35",
   "LastUpdated":"2023-05-03 09:48:35",    
	"Summary": {
		"99:58":{
      	"job_id":58,
      	"num_guids":1,
      	"num_rails":1,
      	"trees":{
       	  	"0":{
        	    "tree_id":0,
            	"type":"LLT",
            	"ANs":{
               	"0x33333":{
                  	"description":"sw3",
                  	"lid":23,
                  	"rank":1,
                  	"guid":"0x33333",
                  	"parent_guid":null,
                  	"child_guids":null,
                  	"hca_guids":["0x78395179", "0x78395178"]
               		}
            	}
         	}
      	},
      	"reservation_key":"99"
   	},
   	"99:74":{
      	"job_id":74,
      	"num_guids":1,
      	"num_rails":1,
      	"trees":{
         	"0":{
            	"tree_id":0,
            	"type":"LLT",
            	"ANs":{
               		"0x33333":{
                  	"description":"sw3",
                  	"lid":23,
                  	"rank":1,
                  	"guid":"0x33333",
                  	"parent_guid":null,
                  	"child_guids":null,
                  	"hca_guids":["0x78395179", "0x78395178"]
               		}
            	},
            	"reservation_key":"99"
         	}
      	}
   		}
	},
   "RelatedObjects":[],
   "CreatedBy":"admin",
   "Operation":"Get sharp jobs",
   "Foreground":true,
   "SiteName":""
}

Get Specific SHARP Non-Blocking Job

Description – Retrieves specific active SHARP jobs with specific reservation_id using non blocking SHARP API
Request URL – GET /ufmRest/app/sharp/resources/jobs_nb/<job_id>?reservation_id=<reservation_id>
Request Content Type – Application/json
Status Codes 200 – OK404 – NOT_FOUND

Response – the HTTP Response location header contains a URL with job ID created for running the action. Example:

{
   "ID":"1",
   "Status":"Completed",
   "Progress":100,
   "Description":"Get sharp jobs",
   "Created":"2023-05-03 09:48:35",
   "LastUpdated":"2023-05-03 09:48:35",    
	"Summary": {
		"99:58":{
      	"job_id":58,
      	"num_guids":1,
      	"num_rails":1,
      	"trees":{
         	"0":{
            	"tree_id":0,
            	"type":"LLT",
            	"ANs":{
               		"0x33333":{
                  	"description":"sw3",
                  	"lid":23,
                  	"rank":1,
                  	"guid":"0x33333",
                  	"parent_guid":null,
                  	"child_guids":null,
                  	"hca_guids":["0x78395179", "0x78395178"]  
                    }
            	}
         	}
      	},
      	"reservation_key":"99"
  },
  "RelatedObjects":[],
   "CreatedBy":"admin",
   "Operation":"Get sharp jobs",
   "Foreground":true,
   "SiteName":""
}

Last updated: March 12, 2026