---
id: field-visibility
slug: /apis/field-visibility
title: 'Field Visibility'
description: 'Discover which attributes are appropriate to show a user for a given asset type, scope and licence — api/visibleFields, api/visibleFieldsByAsset, api/customFields and api/canbeimportant.'
sidebar_label: 'Overview'
sidebar_position: 1
tags: ['api', 'fields', 'visibility', 'metadata']
---

Four small endpoints answer a question [`meta.v1`](/apis/meta-v1) deliberately does not: **of
all the attributes that exist on an asset type, which ones should this user actually be shown?**

`meta.v1` describes the schema — every attribute the type has, everywhere, for everyone. That is
the right answer for a client that needs the full model, and the wrong answer for a client
building a form or a grid. What is appropriate to display depends on the workspace (Scheme)
configuration for the project, on licensing, and on which fields an administrator has chosen to
display. These endpoints apply those rules. See [what is left out](#what-is-left-out) for the gaps.

## The Endpoints

| Endpoint | Method | Answers |
| --- | --- | --- |
| [`api/visibleFields`](/apis/field-visibility/visible-fields) | `GET` | Which fields to show for these asset types, in these scopes? |
| [`api/visibleFieldsByAsset`](/apis/field-visibility/visible-fields#by-asset) | `GET` | Which fields to show for *this specific asset*? |
| [`api/customFields`](/apis/field-visibility/custom-fields) | **`POST`** | Which *custom* fields are visible for this asset? |
| [`api/canbeimportant`](/apis/field-visibility/can-be-important) | `POST` | Can each of these attributes be flagged important? |

:::warning
`api/customFields` is a **`POST`** despite reading like a `GET` — a `GET` returns `405`.
:::

## Columns and Attributes — the Distinction Behind These Endpoints

What users see are **columns**; what the API models are **attributes** — and
visibility flows between them in a loop worth understanding:

- A **column** is a user-visible projection of asset attributes — what
  appears in asset detail views, grids and other views. A column can span
  **multiple related assets and attribute definitions** at once; a few
  special columns project no attribute at all.
- **Visibility configuration is recorded against attributes**, per project
  through the workspace configuration or globally. Two rules sit above the
  configuration: unlicensed attributes are always hidden, and attributes the
  system requires are always shown.
- **A column's visibility is computed from its parts**: a column hides when
  licensing says so, when every asset type it spans is hidden, or when an
  attribute it projects is hidden. Columns that track one attribute across
  several types are gentler — hidden only when *all* their attributes are —
  so hiding one type's copy of a field does not hide its siblings'.
- **These endpoints close the loop**: they walk the columns this user would
  see and answer in attribute terms — which attributes underlie the visible
  columns.

One more word you will meet: **field**. In conversation (and in the admin
UI's "display fields"), *field*, *column* and *attribute* get used
interchangeably — but a field is purely a UX concept, the presentation of a
column or attribute on screen, potentially for editing. It has no
counterpart in the domain model, which knows only attributes and the columns
that project them.

## What Is Left Out

The filtering these endpoints apply is narrower than "everything an administrator configured",
and the omissions are deliberate.

- **Only the simplest kinds of columns are considered** — those that project
  a single attribute directly, plus a few special-purpose ones. A column
  rendered by more complex machinery is skipped, as are columns built by
  joining across attributes. That's a known gap, not a bug.
- An attribute is included if it can be displayed on the display-fields page **or** is required
  by the system.
- Results are de-duplicated **by attribute name** and returned sorted by name.

Treat the result as "safe to show", not as "the complete set of fields this user could ever
see".

## Authentication

All four require authentication except `api/canbeimportant`, which carries no authorization
attribute at all — see [that page](/apis/field-visibility/can-be-important) for what that does
and does not imply.

## Related

- [Meta API](/apis/meta-v1) — the full schema, unfiltered
- [Attribute types](/reference/attribute-types)
- [Attribute paths](/reference/query-grammar/attribute-paths) — addressing attributes in queries