> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.endorlabs.com/feedback

```json
{
  "path": "/developers-api/rest-api/using-the-rest-api/masks/index",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Masks

> Learn how to use field masks with the Endor Labs REST API.

Field masks allow you to specify a subset of fields that each returned object includes.
Similar to [filter keys](/developers-api/rest-api/using-the-rest-api/filters#keys), a field-mask key specifies the field to return, using a dot-delimited path.

The following example shows how to get just the description and severity for all findings:

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api list --resource Finding \
      --field-mask "meta.description,spec.level"
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl --get \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level"
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com
    @token = `<insert-access-token>`
    @namespace = `<insert-namespace>`

    ###
    GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.mask=meta.description,spec.level HTTP/1.1
    Authorization: Bearer {{token}}
    ```
  </Tab>
</Tabs>

## jq

The Endor Labs REST API returns results in json format so it is often convenient to use the `jq` command-line json processor to parse or format the results.

The following example shows how to use `jq` to extract just the description value from the above request:

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api list --resource Finding \
      --field-mask "meta.description,spec.level" \
      | jq '.list.objects[].meta.description'
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl --get \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level" \
      | jq '.list.objects[].meta.description'
    ```
  </Tab>
</Tabs>

<Note>
  Lists of objects are always nested under `.list.objects[]`, but `endorctl api get` returns a single object directly.
  To extract the object UUID from an object returned by an `endorctl api get` command, the `jq` command is `jq '.uuid'`, as opposed to `jq '.list.objects[].uuid'`.
</Note>

For more information, see the [jq documentation](https://jqlang.github.io/jq/tutorial/).