Workload templates

This set of endpoints manages workload templates used to define reusable workload configurations across various workload types in the NVIDIA Run:ai platform. Templates help standardize workload definitions for consistent submission and resource usage across projects and users.

List templates. [Experimental]

Retrieve all available templates.

SecuritybearerAuth
Request
query Parameters
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
sortBy
string

Sort results by parameter.

Enum: "name" "workloadType" "runnable" "scopeType" "clusterId" "projectId" "departmentId" "createdAt" "updatedAt" "createdBy" "updatedBy"
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: filterBy=name!=some-template-name,createdAt>=2021-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/workload-templates
Response samples
application/json
{
  • "entries": [
    ],
  • "pagination": {
    }
}

Get a template, any type. [Experimental]

Retrieve the details of a template using its id.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/{templateId}
Response samples
application/json
{
  • "meta": {
    },
  • "runnable": {
    },
  • "spec": {
    },
  • "assets": { },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "combinedSpec": {
    },
  • "combinedMasterSpec": {
    }
}

Count templates. [Experimental]

Get the total number of templates.

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: filterBy=name!=some-template-name,createdAt>=2021-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/count
Response samples
application/json
{
  • "count": 1
}

Create a new workspace template. [Experimental]

Create a new workspace template.

SecuritybearerAuth
Request
Request Body schema: application/json
required
object (TemplateCreationMetaFields)
object or null (WorkspaceSpecSpec)
Responses
202

Request completed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

post/api/v1/workload-templates/workspaces
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

List all workspace templates. [Experimental]

List all workspace templates.

SecuritybearerAuth
Request
query Parameters
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
sortBy
string

Sort results by parameter.

Enum: "name" "workloadType" "runnable" "scopeType" "clusterId" "projectId" "departmentId" "createdAt" "updatedAt" "createdBy" "updatedBy"
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: filterBy=name!=some-template-name,createdAt>=2021-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/workspaces
Response samples
application/json
{
  • "entries": [
    ],
  • "pagination": {
    }
}

Retrieve a specific workspace template by ID. [Experimental]

Retrieve a specific workspace template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/workspaces/{templateId}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Delete a workspace template by ID. [Experimental]

Delete a workspace template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
204

No Content.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

delete/api/v1/workload-templates/workspaces/{templateId}
Response samples
application/json
{
  • "code": 401,
  • "message": "Issuer is not familiar."
}

Patch a workspace template by ID. [Experimental]

Patch a workspace template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
object or null (TemplatePatchMetaFields)
object or null (WorkspaceSpecSpec)
fieldsToClear
Array of strings
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

patch/api/v1/workload-templates/workspaces/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "fieldsToClear": [
    ]
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Update a workspace template by ID. [Experimental]

Update a workspace template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
required
object (TemplateUpdateMetaFields)
object or null (WorkspaceSpecSpec)
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

put/api/v1/workload-templates/workspaces/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Create a new training template. [Experimental]

Create a new training template.

SecuritybearerAuth
Request
Request Body schema: application/json
required
object (TemplateCreationMetaFields)
object or null (TrainingSpecSpec)
Responses
202

Request completed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

post/api/v1/workload-templates/trainings
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

List all training templates. [Experimental]

List all training templates.

SecuritybearerAuth
Request
query Parameters
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
sortBy
string

Sort results by parameter.

Enum: "name" "workloadType" "runnable" "scopeType" "clusterId" "projectId" "departmentId" "createdAt" "updatedAt" "createdBy" "updatedBy"
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: filterBy=name!=some-template-name,createdAt>=2021-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/trainings
Response samples
application/json
{
  • "entries": [
    ],
  • "pagination": {
    }
}

Retrieve a specific training template by ID. [Experimental]

Retrieve a specific training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/trainings/{templateId}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Delete a training template by ID. [Experimental]

Delete a training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
204

No Content.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

delete/api/v1/workload-templates/trainings/{templateId}
Response samples
application/json
{
  • "code": 401,
  • "message": "Issuer is not familiar."
}

Patch a training template by ID. [Experimental]

Patch a training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
object or null (TemplatePatchMetaFields)
object or null (TrainingSpecSpec)
fieldsToClear
Array of strings
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

patch/api/v1/workload-templates/trainings/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "fieldsToClear": [
    ]
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Update a training template by ID. [Experimental]

Update a training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
required
object (TemplateUpdateMetaFields)
object or null (TrainingSpecSpec)
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

put/api/v1/workload-templates/trainings/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    }
}

Create a new distributed training template. [Experimental]

Create a new distributed training template.

SecuritybearerAuth
Request
Request Body schema: application/json
required
object (TemplateCreationMetaFields)
object or null (DistributedSpecSpec)

The spec of the worker(s).

masterSpecSameAsWorker
boolean or null (MasterSpecSameAsWorker)

used for distributed workloads to indicate that the master spec should be the same as the worker spec. in this case, masterSpec should not be specified.

object or null (TemplateMasterSection)
Responses
202

Request completed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

post/api/v1/workload-templates/distributed
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    },
  • "combinedMasterSpec": {
    }
}

List all distributed training templates. [Experimental]

List all distributed training templates.

SecuritybearerAuth
Request
query Parameters
offset
integer <int32>

The offset of the first item returned in the collection.

Example: offset=100
limit
integer <int32> [ 1 .. 500 ]
Default: 50

The maximum number of entries to return.

sortOrder
string
Default: "asc"

Sort results in descending or ascending order.

Enum: "asc" "desc"
sortBy
string

Sort results by parameter.

Enum: "name" "workloadType" "runnable" "scopeType" "clusterId" "projectId" "departmentId" "createdAt" "updatedAt" "createdBy" "updatedBy"
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contain, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: filterBy=name!=some-template-name,createdAt>=2021-01-01T00:00:00Z
search
string

Filter results by a free text search.

Example: search=test project
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/distributed
Response samples
application/json
{
  • "entries": [
    ],
  • "pagination": {
    }
}

Get a specific distributed training template by ID. [Experimental]

Get a specific distributed training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/workload-templates/distributed/{templateId}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    },
  • "combinedMasterSpec": {
    }
}

Delete a distributed training template by ID. [Experimental]

Delete a distributed training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
204

No Content.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

delete/api/v1/workload-templates/distributed/{templateId}
Response samples
application/json
{
  • "code": 401,
  • "message": "Issuer is not familiar."
}

Patch a distributed training template by ID. [Experimental]

Patch a distributed training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
object or null (TemplatePatchMetaFields)
object or null (DistributedSpecSpec)

The spec of the worker(s).

masterSpecSameAsWorker
boolean or null (MasterSpecSameAsWorker)

used for distributed workloads to indicate that the master spec should be the same as the worker spec. in this case, masterSpec should not be specified.

object or null (TemplateMasterSection)
fieldsToClear
Array of strings
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

patch/api/v1/workload-templates/distributed/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "fieldsToClear": [
    ]
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    },
  • "combinedMasterSpec": {
    }
}

Update a distributed training template by ID. [Experimental]

Update a distributed training template by ID.

SecuritybearerAuth
Request
path Parameters
templateId
required
string <uuid>

The Universally Unique Identifier (UUID) of the template.

Example: 550e8400-e29b-41d4-a716-446655440000
Request Body schema: application/json
required
object (TemplateUpdateMetaFields)
object or null (DistributedSpecSpec)

The spec of the worker(s).

masterSpecSameAsWorker
boolean or null (MasterSpecSameAsWorker)

used for distributed workloads to indicate that the master spec should be the same as the worker spec. in this case, masterSpec should not be specified.

object or null (TemplateMasterSection)
Responses
200

Executed successfully.

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

put/api/v1/workload-templates/distributed/{templateId}
Request samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    }
}
Response samples
application/json
{
  • "meta": {
    },
  • "spec": {
    },
  • "masterSpecSameAsWorker": true,
  • "master": {
    },
  • "runnable": {
    },
  • "combinedSpec": {
    },
  • "combinedMasterSpec": {
    }
}