Graph

get_backlinks

Backlinks. Read-only. Idempotent.

List the notes that link to a note.

Use get_context when you also need its outlinks or similar notes.

Parameters

Name	Type	Default	Description
path	string	required	Path of the note linked to, such as "notes/topic.md"; case-sensitive.
limit	integer \| null	null	Maximum backlinks to return; omit for all.
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

List of backlink dicts, each with:

• source_path (str): Path of the document containing the link.
• source_title (str): Title of the source document.
• link_text (str): The clickable text of the link.
• link_type (str): One of "markdown", "wikilink", or "reference".
• fragment (str | None): Heading anchor (such as "#section"), or null.
• raw_target (str): Literal link target as written in the source.

Index freshness is reported out-of-band in the response's _meta.index_stale field: True when the IndexWriter had pending or in-flight work at any of three observation points (wait_for_pending_writes timing out, a write completing inside the read window, or non-idle at response time), False when the data is current as of response time.

Outcomes and errors

• ValueError: If no document exists at the given path.
• ToolError: If the index is busy or still building; retry shortly.
• IndexUnavailableError: If the index build failed or the index is broken; get_index_status reports the error.

{"path": "3-Resources/okf.md", "limit": 5}

returns

[{"source_path": "1-Projects/export.md", "source_title": "Export", "link_text": "OKF", "link_type": "wikilink", "fragment": null, "raw_target": "okf"}]

get_outlinks

Outlinks. Read-only. Idempotent.

List the links in a note, each with an exists flag that is false when the target is missing.

Use get_context when you also need its backlinks or similar notes.

Parameters

Name	Type	Default	Description
path	string	required	Path of the note holding the links, such as "notes/topic.md"; case-sensitive.
limit	integer \| null	null	Maximum outlinks to return; omit for all.
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

List of outlink dicts, each with:

• target_path (str): Path of the linked document.
• link_text (str): The clickable text of the link.
• link_type (str): One of "markdown", "wikilink", or "reference".
• fragment (str | None): Heading anchor (such as "#section"), or null.
• raw_target (str): Literal link target as written in the source.
• exists (bool): True if the target document is indexed.

A reference to an attachment is not a link, so it is not listed.

Index freshness is reported out-of-band in the response's _meta.index_stale field: True when the IndexWriter had pending or in-flight work at any of three observation points (wait_for_pending_writes timing out, a write completing inside the read window, or non-idle at response time), False when the data is current as of response time.

Outcomes and errors

• ValueError: If no document exists at the given path.
• ToolError: If the index is busy or still building; retry shortly.
• IndexUnavailableError: If the index build failed or the index is broken; get_index_status reports the error.

get_broken_links

Broken Links. Read-only. Idempotent.

List the links whose target is missing from the vault, each with the note that holds it.

stats reports broken_link_count; a rename without update_links leaves such links behind. Links to attachments are not checked.

Parameters

Name	Type	Default	Description
folder	string \| null	null	Only links in notes in this folder and its sub-folders, such as "Journal"; "" for top-level notes only; omit for the whole vault.
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

List of dicts, each with:

• source_path (str): Path of the document containing the broken link.
• source_title (str): Title of the source document.
• target_path (str): The missing target path.
• link_text (str): The clickable text of the link.
• link_type (str): One of "markdown", "wikilink", or "reference".
• fragment (str | None): Heading anchor (such as "#section"), or null.
• raw_target (str): Literal link target as written in the source.

Index freshness rides in the response's _meta.index_stale field: True when the IndexWriter was non-idle, a write completed inside the read window, or wait_for_pending_writes timed out; False otherwise.

get_orphan_notes

Orphan Notes. Read-only. Idempotent.

List every note with no links in or out, with no limit on the count.

stats reports orphan_count; check it first on a large vault.

Parameters

Name	Type	Default	Description
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

List of dicts ordered by path, each with:

• path (str): Relative path of the orphan note.
• title (str): Title of the note.
• folder (str): Folder containing the note.
• frontmatter (dict): Parsed YAML frontmatter.
• modified_at (float): Unix timestamp of last modification.
• kind (str): Always "note".
• content_chars (int): body length in characters, frontmatter excluded; 0 for a note indexed before the field existed.

A reference to an attachment is not a link, so a note whose only links are to attachments is an orphan.

Index freshness rides in the response's _meta.index_stale field: True when the IndexWriter was non-idle, a write completed inside the read window, or wait_for_pending_writes timed out; False otherwise.

get_most_linked

Most-Linked Notes. Read-only. Idempotent.

List the notes with the most backlinks, most first.

Use get_backlinks for the notes that link to one of them.

Parameters

Name	Type	Default	Description
limit	integer	10	Maximum notes to return (default 10).
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

List of dicts with path (str), title (str), folder (str), and backlink_count (int: number of distinct source documents linking to this note), ordered by backlink_count descending.

Index freshness rides in the response's _meta.index_stale field: True when the IndexWriter was non-idle, a write completed inside the read window, or wait_for_pending_writes timed out; False otherwise.

get_connection_path

Connection Path. Read-only. Idempotent.

Find the shortest chain of links between two notes, following links in either direction.

Parameters

Name	Type	Default	Description
source	string	required	Path of the starting note, such as "Ideas/spark.md".
target	string	required	Path of the destination note.
max_depth	integer	10	Most links to follow, 1 to 10 (default 10).
wait_for_pending_writes	boolean	false	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Returns

Dict with the connection-path result. Fields:

• found (bool): Whether a path was found within max_depth hops.
• path (list[str]): Note paths in order from source to target, or an empty list if not found.
• hops (int): Number of edges in the path (len(path) - 1), or -1 if not found.

Index freshness is reported out-of-band in the response's _meta.index_stale field: True when the IndexWriter had pending or in-flight work at any of three observation points (wait_for_pending_writes timing out, a write completing inside the read window, or non-idle at response time), False otherwise.

Outcomes and errors

• DocumentNotFoundError: If either note does not exist.
• ToolError: If the index is busy or still building; retry shortly.
• IndexUnavailableError: If the index build failed or the index is broken; get_index_status reports the error.

{"source": "Ideas/spark.md", "target": "3-Resources/okf.md", "max_depth": 4}

returns

{"found": true, "path": ["Ideas/spark.md", "1-Projects/export.md", "3-Resources/okf.md"], "hops": 2}