> This page is for Self-Hosted, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server.

# Get mapping field info. [experimental]

POST http://localhost:8080/api/v1/policies/mappings/field-info
Content-Type: application/json

Retrieve the detailed breakdown for one or more field references in a workload type's mapping.

Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/policies/policy/get-mapping-field-info

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication

## Request

### Body (application/json)

This endpoint expects a GetMappingFieldInfoReq.

- `workloadType` (GVK, optional) — The Kubernetes group, version, and kind of the workload type whose mapping is queried.
- `fieldsRef` (list of BreakdownFieldRef, optional) — The field references to retrieve the detailed breakdown for.

## Response

### 200

The detailed breakdown of the requested fields.

- `breakdown` (BreakdownBreakdown, optional, nullable) — The detailed breakdown, keyed into per-field variations and per-spec-selector details.

## Errors

### 400 Bad Request Error

Bad request.

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 401 Unauthorized Error

Unauthorized

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 403 Forbidden Error

Forbidden

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 404 Not Found Error

The specified resource was not found

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 503 Service Unavailable Error

unexpected error

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

## Types

### GVK

Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.

- `version` (string, required) — The API version of the resource within the specified group.
- `kind` (string, required) — The type of Kubernetes resource being referenced.
- `group` (string, optional, nullable) — The API group of the Kubernetes resource. Empty string for core resources like Pod.

### BreakdownFieldRef

A reference to a single field within a workload type's mapping.

- `fieldName` (string, optional) — The name of the field to retrieve the breakdown for.
- `specSelector` (string, optional, nullable) — The name of the spec selector that exposes the field. Optional; when omitted, the breakdown includes all spec selectors that expose the field.
- `itemSelector` (string, optional, nullable) — The name of the item selector that applies to the field. Optional; omit for non-itemized fields.

### BreakdownBreakdown

The detailed breakdown, keyed into per-field variations and per-spec-selector details.

- `fields` (map from string to list of BreakdownFieldVariation, optional) — The detailed breakdown of fields, keyed by field name. Each field maps to the list of its variations across the requested spec selectors and item selectors.
- `specSelectors` (map from string to BreakdownSpecSelector, optional) — The detailed breakdown of spec selectors, keyed by spec-selector name.

### BreakdownFieldVariation

A single variation of a field in the breakdown: the spec selectors it appears under, how it is read and written (formatter details or a direct specRef), its data type, and the item-selector queries that apply to it.

- `specSelectors` (list of string, optional) — The spec selectors under which this variation of the field appears.
- `formatter` (BreakdownFormatter, optional) — The formatter details for a field in the breakdown: either the name of the built-in formatter used, or the resolved getExpr/setExpr, arrayKey, and argument type/enum information.
- `specRef` (string, optional) — A direct dotted path into the workload spec, used in place of a formatter for simple fields.
- `type` (enum, optional) — The data type of the field.
  - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object`
- `itemSelectors` (map from string to BreakdownItemSelector, optional) — The item selectors that apply to the field, keyed by item-selector name, with each value containing the item selector's JQ query and argument metadata.
- `possibleEnforcements` (list of enum, optional) — The enforcement types that may be applied to this variation of the field. Derived from the field's data type, with `items` added when the field is itemized (has an itemSelector).
  - Allowed values: `set`, `default`, `required`, `blocked`, `match`, `options`, `length`, `range`, `quantityRange`, `elements`, `items`

### BreakdownSpecSelector

The details of a single spec selector in the breakdown: its description, JQ query, and the type and enum information for any arguments referenced by the query.

- `description` (string, optional) — A free-text description of the element.
- `query` (string, optional) — The JQ query used to select a subtree of the workload spec. Consult https://jqlang.org/manual/ for further info.
- `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\<argName>.
  - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object`
- `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\<argName>. Up to 100 values per argument.
- `dependency` (SpecSelectorDependency, optional) — Declares that this spec selector depends on a parent path existing. The engine will ensure the element path exists before running SET/DEFAULT actions that target this selector.

### BreakdownFormatter

The formatter details for a field in the breakdown: either the name of the built-in formatter used, or the resolved getExpr/setExpr, arrayKey, and argument type/enum information.

- `builtin` (string, optional, nullable) — The name of the built-in formatter, if used.
- `setExpr` (string, optional, nullable) — The JQ expression used to write the field value into the workload spec. Consult https://jqlang.org/manual/ for further info.
- `getExpr` (string, optional, nullable) — The JQ expression used to read the field value from the workload spec. Consult https://jqlang.org/manual/ for further info.
- `arrayKey` (FormatterArrayKey, optional, nullable) — The unique key per item for an itemized field, provided as an argName with an optional specRef.
- `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\<argName>.
  - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object`
- `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\<argName>. Up to 100 values per argument.

### BreakdownItemSelector

The details of a single item selector in the breakdown: its JQ query, and the type and enum information for any arguments referenced by the query.

- `query` (string, optional) — The JQ query used to filter items of an itemized field. Consult https://jqlang.org/manual/ for further info.
- `argsInfo` (map from string to enum, optional) — The data type of each argument referenced by the JQ expression as \$ARGS.named.\<argName>.
  - Allowed values: `string`, `boolean`, `integer`, `number`, `quantity`, `ipaddress`, `integers`, `numbers`, `strings`, `namesArray`, `object`
- `argsEnum` (map from string to list of string, optional) — The allowed values for each string-typed argument referenced by the JQ expression as \$ARGS.named.\<argName>. Up to 100 values per argument.

### SpecSelectorDependency

Declares that this spec selector depends on a parent path existing. The engine will ensure the element path exists before running SET/DEFAULT actions that target this selector.

- `specSelector` (string, optional, nullable) — Optional parent spec selector that provides iteration context. When set, the element path is created relative to each result of the parent selector. When omitted, element is relative to the workload root.
- `path` (string, optional) — Dot-separated path to ensure exists below the parent. Example: "template.metadata" creates both .template and .template.metadata if missing.

### FormatterArrayKey

The unique key per item for an itemized field, provided as an argName with an optional specRef.

- `argName` (string, required) — The name of the argument that supplies the unique key value per item.
- `specRef` (string, optional, nullable) — An optional direct dotted path into the workload spec that locates the key value for each item.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "breakdown": {
    "fields": {},
    "specSelectors": {}
  }
}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/api/v1/policies/mappings/field-info"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'http://localhost:8080/api/v1/policies/mappings/field-info';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8080/api/v1/policies/mappings/field-info"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/policies/mappings/field-info")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("http://localhost:8080/api/v1/policies/mappings/field-info")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'http://localhost:8080/api/v1/policies/mappings/field-info', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("http://localhost:8080/api/v1/policies/mappings/field-info");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v1/policies/mappings/field-info")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```