# The rows a link column may point to, for one row: what an agent or a picker offers before writing

`POST /datanotes/operations/list_link_targets/` (operation `list_link_targets`)

The rows a link column may point to, for one row: what an agent or a picker offers before writing
the link. A link column can filter its targets:
- `ref_where`: a `where` filter every target must match (`{"kind": {"in": ["area", "project"]}}`).
- `ref_by`: a column of the row picks the targets' level: `{"column": "kind", "map": {"area": null,
  "project": ["area"], "workstream": ["project"]}}`: a workstream's parent must have kind project; `null`
  is a top level (the link must stay empty); any other level needs the link; a value missing from the
  map is refused. `levels: ["area", "project", "workstream"]` writes the same chain short (each
  level's parent is the level before it). `target_column` reads another column of the target
  (default: the same name). describe_table shows the expanded map.
Writes refuse other targets (code `ref`, listing the valid ones), a link to the row itself (`ref`),
a link to no row of the table (`broken_link`) and a missing link a level needs (`required`). Pass the
row (`row`: path, link or name; a name rows in different folders share is refused, listing their
paths) and/or its values (`values`, e.g. `{"kind": "workstream"}` for a new row). Returns
`{rows: [{name, link, path, <level column>}], total, required, empty, reason}` (no rows, and the
reason, for a level the map lacks); write a row's `link` as the value.

## Request body

`application/json`, required

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `table` | `string` | yes |  |  |
| `column` | `string` | yes |  | A link column (or list of links) with ref. |
| `row` | `string \| null` | no | `null` | The row the link is for: its path, a link to it or its name (its values are read). |
| `values` | `object \| null` | no | `null` | Values of the row (a new one, or changes to `row`), e.g. {"kind": "workstream"}. |
| `limit` | `integer \| null` | no | `null` | At most this many targets: a positive integer (default 50, at most 500). |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Done. | `object` (application/json) |
| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
| 401 | Missing or wrong bearer token. | `Error` (application/json) |
| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
| 500 | Unexpected error. | `Error` (application/json) |

The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).