--- title: "URL Parameters" diataxis: reference applies_to: product: "nirmata-control-hub" audience: ["platform-engineer","developer"] last_updated: 2026-03-25 url: https://docs.nirmata.io/docs/reference/rest-api/url_parameters/ --- URL Parameters are used to control the returned JSON data. ## mode The mode parameter is used to control the JSON output format for a GET request. Here are the allowed values: - normal - export - exportDetails In the *normal* mode the JSON data for each object contains all attributes and relations are output as links. In the *export* mode the JSON data contains all attributes and child relation objects are directly embedded into the parent. Reference relations are represented as links, and also contain the unique attributes of the referred to object. The mode parameter can be applied to all GET requests and can be combined with other parameters. The export mode is useful when an entire sub-document needs to be retrieved and stored externally. For example, the following query will export the full {model} as JSON: GET https://www.nirmata.io/catalog/api/applications/{id}?mode=export Accept: application/json The *exportDetails* mode also includes meta-data fields and relations to external entities (outside of the target document). ## query The query parameter is used to control which objects are included in a JSON response. The query data is specified as a JSON object. The query parameter can be applied to any GET request that returns multiple objects. For example the following query returns the application named 'helloworld': GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld"} Accept: application/json Multiple attributes can be specified for a logical AND operation: GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld", "run" : "hello1"} Accept: application/json ## fields The fields parameter is used to control which fields, of an resource, should be included in the JSON response. The fields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be included in the response. For example, this query returns only the *id* and *name* fields of all Deployments in the catalog: GET https://www.nirmata.io/catalog/api/deployments?fields=id,name,kind,apiVersion Accept: application/json ## excludeFields The excludeFields parameter is used to exclude one or more fields from the response. The excludeFields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be excluded from the response. For example, this query excludes the *metadata* field from Deployments: GET https://www.nirmata.io/catalog/api/deployments?excludefields=metadata Accept: application/json ## count The count parameter is used to specify the maximum number of resources to be returned. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified, all matching resources are returned. For example the following query returns the podIP and state fields for up to 10 instances of the resource *podStatus*: GET https://www.nirmata.io/environments/api/podStatus?count=10&fields=podIP,state Accept: application/json ## start The start parameter is used to specify the start index in a list of resources. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified a value of 0 is assumed. For example the following query returns *podStatus* instances 10-20 (or less) that have attribute state with the *state* of *running*: GET https://www.nirmata.io/environments/api/podStatus?start=10&count=10&query={"state" : "running"}&fields=id Accept: application/json --- ## mode The mode parameter is used to control the JSON output format for a GET request. Here are the allowed values: - normal - export - exportDetails In the *normal* mode the JSON data for each object contains all attributes and relations are output as links. In the *export* mode the JSON data contains all attributes and child relation objects are directly embedded into the parent. Reference relations are represented as links, and also contain the unique attributes of the referred to object. The mode parameter can be applied to all GET requests and can be combined with other parameters. The export mode is useful when an entire sub-document needs to be retrieved and stored externally. For example, the following query will export the full {model} as JSON: GET https://www.nirmata.io/catalog/api/applications/{id}?mode=export Accept: application/json The *exportDetails* mode also includes meta-data fields and relations to external entities (outside of the target document). --- ## query **NOTE: the query parameter is deprecated. Use [`filter`](../filter/_index.md) instead** The query parameter is used to control which objects are included in a JSON response. The query data is specified as a JSON object. The query parameter can be applied to any GET request that returns multiple objects. For example the following query returns the application named 'helloworld': GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld"} Accept: application/json Multiple attributes can be specified for a logical AND operation: GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld", "run" : "hello1"} Accept: application/json --- ## fields The fields parameter is used to control which fields, of an resource, should be included in the JSON response. The fields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be included in the response. For example, this query returns only the *id* and *name* fields of all Deployments in the catalog: GET https://www.nirmata.io/catalog/api/deployments?fields=id,name,kind,apiVersion Accept: application/json --- ## filter The `filter` parameter is used to filter the results based on values. Multiple filters can be provided. Each filter is a 3-tuple comma-delimited expression: `fieldName,operator,value` * **fieldName**: The field names can be attributes or sub-attributes (i.e. nested values) specified using a JSON path syntax using `.` for delimiters. For example `rules.type` will check the `type` attribute in the nested `rules` object array. * **operator**: the following operators are supported: * `eq`, `equals` * `ne`, `notEquals` * `gt`, `greaterThan` * `lt`, `lessThan` * `gte`, `greaterThanOrEquals` * `lte`, `lessThanOrEquals` * `sw`, `startswith` * `ew`, `endswith` * `cs`, `contains` * **value**: the field JSON value This query returns the IDs and names of all policies with mutate rules: ```sh nctl raw "/policies/api/policy?filter=rules.type,equals,Mutation&fields=id,name" | jq ``` **results:** ```json [ { "id": "9ddaac9f-075f-4e69-a1bc-a0243d2f6072", "name": "disable-automount-sa-token" }, { "id": "668bbd6a-c433-41a2-ab1d-325120ed14f2", "name": "check-images" }, { "id": "44ec005e-f7ed-431f-99ba-89918205fe6c", "name": "disable-automount-sa-token" } ] ```text --- ## paginate The `paginate` parameter is used to return results in a pagination friendly format. It can be used in conjunction with the [count](../count/_index.md) and [start](../start/_index.md) parameters. This query returns the `id` and `name` attributes of first 5 policies: ```sh nctl raw "/policies/api/policy?fields=name,id&paginate=true&start=0&count=5" | jq ``` **results:** ```json { "start": 0, "count": 5, "total": 65, "entries": [ { "id": "f86d6075-569c-4fe5-a8cd-4df6fe012e19", "name": "add-networkpolicy-dns" }, { "id": "9ddaac9f-075f-4e69-a1bc-a0243d2f6072", "name": "disable-automount-sa-token" }, { "id": "38d8b01c-cb2d-4414-8fbe-e673b0225542", "name": "disallow-capabilities" }, { "id": "b8593a74-c92c-4906-a514-54081d8e8bae", "name": "disallow-capabilities-strict" }, { "id": "2e7da966-2a29-4fbe-a8ba-03d146cdcf1c", "name": "disallow-host-namespaces" } ] } ```text --- ## excludeFields The excludeFields parameter is used to exclude one or more fields from the response. The excludeFields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be excluded from the response. For example, this query excludes the *metadata* field from Deployments: GET https://www.nirmata.io/catalog/api/deployments?excludefields=metadata Accept: application/json --- ## count The count parameter is used to specify the maximum number of resources to be returned. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified, all matching resources are returned. For example the following query returns the podIP and state fields for up to 10 instances of the resource *podStatus*: GET https://www.nirmata.io/environments/api/podStatus?count=10&fields=podIP,state Accept: application/json --- ## sort The `sort` parameter is used to sort results: This query returns policies with `rules.type` equals `Mutation` in alphabetical order: ```sh nctl raw "/policies/api/policy?filter=rules.type,equals,Mutation&fields=id,name&sort=name,asc" | jq ``` **results:** ```json [ { "id": "668bbd6a-c433-41a2-ab1d-325120ed14f2", "name": "check-images" }, { "id": "9ddaac9f-075f-4e69-a1bc-a0243d2f6072", "name": "disable-automount-sa-token" }, { "id": "44ec005e-f7ed-431f-99ba-89918205fe6c", "name": "disable-automount-sa-token" } ] ```text --- ## start The start parameter is used to specify the start index in a list of resources. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified a value of 0 is assumed. For example the following query returns *podStatus* instances 10-20 (or less) that have attribute state with the *state* of *running*: GET https://www.nirmata.io/environments/api/podStatus?start=10&count=10&query={"state" : "running"}&fields=id Accept: application/json