---
id: valid-values
slug: /apis/valid-values
title: 'Valid Values (api/ValidValues)'
description: 'Ask what values a relation attribute may take - the endpoint the application uses to populate its dropdowns, Team Process included.'
sidebar_label: 'Valid Values (api/ValidValues)'
sidebar_position: 14
tags: ['api', 'valid-values', 'relations', 'workflows']
---

Answers "what values may this relation take?" — the same question the
application answers when it populates a dropdown, honoring the schema's
valid-values filters (where the
[`$` asset-identity variable](/reference/query-grammar/filter-context#reserved-variables)
does its work), the asking context, and
[Team Process](/concepts/workflows). Both routes accept GET or POST and
require authentication.

## By Relation, with a Context

```text
GET ~/api/ValidValues/Story.Status/?context=Scope=Scope:1067
```

The path segment is the full attribute token. **The trailing slash is
required**: the token contains a dot, and without a trailing slash the
web server reads `.Status` as a file extension and answers 404 before the
route is ever consulted. (The existing-asset form below has no dot in its
last segment, so it needs no slash.)

| Parameter | Meaning                                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context` | Comma-separated `Name=Oid` pairs feeding the valid-values filter's variables. Omitted entirely, it defaults to `Scope=Scope:0`; an explicitly **empty** `context=` supplies no context at all, and typically returns nothing. |
| `sel`     | Attributes to return per value; defaults to `Name,ID`.                                                                                                        |
| `sort`    | An attribute of the related type to sort by.                                                                                                                  |

## For an Existing Asset

```text
GET ~/api/ValidValues/Story/1207/Status
```

Evaluates the valid-values filter against the asset's **actual state**, so
the answer reflects everything that narrows it — most usefully, a team's
own workflow. On an instance whose shared `StoryStatus` list is *Future /
In Progress / Done / Accepted*, a story on a team with its own process
answers differently:

```text
GET ~/api/ValidValues/Story/1207/Status
→ Ready, Dev, Dev Done, Test, Test Done, Accepted
```

This is the way to ask **"which statuses may this workitem take?"** before
a write — the values a Team Process enforces on status changes. An
optional `teamoid` parameter supplies the team explicitly. `sel` and
`sort` work as above.

## Response Shape

The envelope looks like a `rest-1.v1` list — `_type: "Assets"`, `total`,
`Assets` with `id` and `Attributes` — and each entry's `href` points at
the asset's `rest-1.v1` address:

```json
{
  "_type": "Assets",
  "total": 4,
  "Assets": [
    {
      "_type": "Asset",
      "href": "~/rest-1.v1/Data/StoryStatus/133",
      "id": "StoryStatus:133",
      "Attributes": {
        "Name": { "_type": "Attribute", "name": "Name", "value": "Future" },
        "ID": { "_type": "Attribute", "name": "ID", "value": "StoryStatus:133" }
      }
    }
  ]
}
```

`pageSize` reports the no-limit sentinel; the endpoint does not page.

## Quick Suggestions (`api/QuickSuggestion`)

The same machinery has a lighter sibling, used for type-ahead:

```text
GET ~/api/QuickSuggestion/Story:1207/Story.Status/
```

The first segment is the asset's OID, the second the full attribute
token — and the trailing slash is required here for the same
dot-in-the-last-segment reason. If the relation defines a **quick-values
filter** (a schema-defined shortlist), the response has
`type: "Suggestions"`; otherwise it falls back to the valid values,
capped at 20, with `type: "ValidValues"`:

```json
{
  "data": {
    "type": "ValidValues",
    "data": [{ "_oid": "StoryStatus:133", "name": "Future" }]
  }
}
```

Use `api/ValidValues` when you need the complete, context-correct answer;
`api/QuickSuggestion` when you want what the application would offer
first in a type-ahead.

## Related Topics

- [Workflows and status](/concepts/workflows) — Team Process and the
  invalid-status violation this endpoint lets you avoid
- [Reserved filter variables](/reference/query-grammar/filter-context#reserved-variables)
  — the `$` the underlying filters are written in
- [Attributes](/concepts/attributes)