# List backlinks

`list_backlinks`

| Through | Form |
|---|---|
| HTTP | `GET https://api.markdownbrain.ai/v1/backlinks` |
| MCP | tool `list_backlinks` |
| CLI | `mdbrain call list_backlinks` |

The documents that link to a file: the list a person sees at the foot of its preview, under *Linked from*. Name the file with `path` or with `file_id` — exactly one of the two. Each entry carries the source's `path`, `file_id`, `title` and `archived`, up to three `lines` (`{ line, text }`) it links from, and `more_lines`, how many further lines link here. Newest change first, `limit` at a time (default 20, at most 100); `total` counts every linking document, so page on with `offset`. A link is counted where it works today. [`rename_node`](/docs/operations/rename_node) and [`move_node`](/docs/operations/move_node) rewrite these links to the new place by default (`update_links`), and break them only with `update_links: false`.

**Who may call it:** agents and people.

**Writes:** no, it only reads.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `file_id` | string | no | query string | file_node id of the file — or use `path` |
| `path` | string | no | query string | Workspace-relative path, e.g. "specs/44-front-matter.md" |
| `workspace_id` | string | no | query string | Only needed to disambiguate a `path` that exists in more than one workspace you can see |
| `limit` | integer | no | query string | How many linking documents to return (default 20, at most 100; 0 for the total alone) |
| `offset` | integer | no | query string | How many to skip, to read the next page (default 0) |

## Success

`200` with `application/json`.

## Example request

```sh
curl 'https://api.markdownbrain.ai/v1/backlinks?path=specs%2F12-onboarding.md&workspace_id=00000000-0000-4000-8000-000000000010&limit=2' \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"
```

```sh
mdbrain call list_backlinks \
  --path specs/12-onboarding.md \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --limit 2
```

## Example response

> Written from the code rather than captured from a call.

```json
{
  "file_id": "00000000-0000-4000-8000-000000000102",
  "workspace_id": "00000000-0000-4000-8000-000000000010",
  "path": "specs/12-onboarding.md",
  "total": 1,
  "backlinks": [
    {
      "path": "specs/09-pricing.md",
      "file_id": "00000000-0000-4000-8000-000000000105",
      "title": "Pricing",
      "archived": false,
      "lines": [
        {
          "line": 14,
          "text": "The trial starts when onboarding ends; see [onboarding](12-onboarding.md)."
        }
      ],
      "more_lines": 0
    }
  ]
}
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).