---
id: visible-fields
title: 'Visible Fields'
description: 'api/visibleFields and api/visibleFieldsByAsset — the attribute names appropriate to display for an asset type in a scope, or for one specific asset.'
sidebar_label: 'Visible Fields'
sidebar_position: 2
tags: ['api', 'fields', 'visibility']
---

Two `GET` endpoints returning attribute **names** that are appropriate to display. They differ
only in how you identify what you are asking about: by asset type and scope, or by a specific
asset.

Both apply the filtering described in the [overview](/apis/field-visibility) — a narrower set
than everything `meta.v1` reports.

## `api/visibleFields`

```http
GET ~/api/visibleFields?scopeOid=Scope:0&assetTypeToken=Story&assetTypeToken=Defect
```

**Both parameters repeat.** Pass `assetTypeToken` once per asset type, and `scopeOid` once per
scope. This is a plain repeated-key query string, not a comma-separated list.

| Parameter | Repeatable | Description |
| --- | --- | --- |
| `scopeOid` | yes | Scope OID tokens providing the context for visibility |
| `assetTypeToken` | yes | Asset types to report on |

### Response

An array with one entry per requested asset type. **Property names are camelCase**, which is
worth noting because the server-side model declares them capitalised — the JSON formatter
lowercases them on the way out.

```json
[
  {
    "assetType": "Story",
    "fields": ["Estimate", "Name", "Number", "Scope", "Status"]
  },
  {
    "assetType": "Defect",
    "fields": ["Name", "Number", "Priority", "Scope", "Status"]
  }
]
```

`fields` is sorted by name and de-duplicated.

:::danger Do not mix global and non-global asset types

Some asset types are *global* — they have no scope context. Requesting a mixture returns
**400** with:

```text
Cannot mix global and non-global asset types.
```

The rule is all-or-nothing:

- **Every** requested type is global → the scope context is ignored entirely and a global
  context is used. `scopeOid` has no effect.
- **No** requested type is global → a multi-scope context is built from the `scopeOid` values.
- **A mixture** → 400.

Split the request in two if you need both.

:::

## `api/visibleFieldsByAsset` \{#by-asset\}

```http
GET ~/api/visibleFieldsByAsset?oidToken=Story:1234
```

| Parameter | Description |
| --- | --- |
| `oidToken` | OID token of the asset to report on |

The server resolves that asset's Scope and uses it as the visibility context, so you do not
supply a scope yourself.

### Response

A flat array of attribute names — note this is a **different shape** from `api/visibleFields`,
which wraps each list in an object with its asset type:

```json
["Estimate", "Name", "Number", "Scope", "Status"]
```

## Custom Fields Are Included

Both endpoints include custom fields once they are configured for display in the scope. This is
the main reason to call them rather than reasoning from `meta.v1` alone: a custom field exists
in the schema regardless, but whether it should be shown depends on workspace configuration
that only these endpoints apply.

If you want *only* the custom fields, use
[`api/customFields`](/apis/field-visibility/custom-fields) — but note it is a `POST`.


## Related

- [Field visibility overview](/apis/field-visibility) — what the filtering does and does not cover
- [Custom fields](/apis/field-visibility/custom-fields)
- [Meta API](/apis/meta-v1)