Document paths

A document path places a document at a location in a pipeline, such as kb.billing.tax.vat, so that a search, an agent or a document list can address one part of the pipeline's content. This page describes the path syntax, paths across versions, path matching, the operations that accept a path and the relationship between paths and access control. Integrators need this page to decide whether a pipeline uses paths and to design a path layout.

Path syntax

A path is a sequence of labels separated by periods. Each label holds one or more lowercase letters, digits, hyphens (-) and underscores (_), and a path holds at most 1,024 characters. A label is never empty, so a path neither starts nor ends with a period and holds no two consecutive periods.

Path	Valid	Reason
kb.billing.tax.vat	Yes	Four labels
team-alpha.2026_q3	Yes	Hyphens, underscores and digits are allowed
kb	Yes	A single label
kb.Billing	No	Uppercase letter
kb/billing	No	Slash instead of a period
kb..billing	No	Empty label
kb.billing.	No	Trailing period

A client application converts the names of its own folders, rooms or projects into labels, for example by lowercasing the name and replacing spaces with hyphens.

Paths and versions

The path field of the document create request sets the path of the new version, as described in Documents, versions and fragments. The field is optional, and a document version without a path has the path null. An invalid path returns HTTP 422 and creates no document.

Each version carries its own path, and a new version does not inherit the path of the previous version:

• Same path. A client application sends the same path with every version of a document.
• Moved document. A new version with a different path moves the document. With expire_older_versions set to true, the default, the previous version expires at submission, and the document appears at the new path when the new version reaches success.
• Path removed. A new version without path has no path. The document then leaves every search that names a path.
• Several current versions. With expire_older_versions set to false, the previous versions remain current at their own paths, so one document can be found at several paths.

Every fragment carries the path of its document version in the path field, in search results, in fragment lists and in the results of agents.

Path matching

A request that selects documents by path names a path pattern. The pattern is a path, or a path whose last label is a wildcard:

Pattern	Matches	Example matches for kb.billing
kb.billing	That path only	kb.billing
kb.billing.*	Paths exactly one level below the path	kb.billing.payment-methods, not kb.billing.tax.vat
kb.billing.>	Paths any number of levels below the path	kb.billing.payment-methods and kb.billing.tax.vat
*	Every path of one label	kb, not kb.billing
>	Every path	Every document with a path

Neither wildcard matches the path before the wildcard: kb.billing.> does not match a document at kb.billing. A wildcard is valid only as the last label, so kb.*.vat is not a valid pattern. The underscore matches only itself.

A search request without path, or with path set to null, searches only the documents without a path. No pattern matches both the documents without a path and the documents with a path, so one search request covers either the documents without a path or the documents under one pattern. A pipeline in which some documents have a path and other documents have none therefore needs two searches to cover every document. A pipeline that gives every document a path, or no document a path, needs one.

Operations that accept a path

Operation	Field	Without the field
Search, POST /pipelines/{id}/search	path in the body, a pattern	Only documents without a path
Agent retrieval and execution, POST /agents/{id}/search and POST /agents/{id}/execute	path in the body, a pattern applied to every placeholder of the agent	Only documents without a path
Document list, GET /pipelines/{id}/documents	path query parameter, a pattern	Every document
Path list, GET /pipelines/{id}/paths	path query parameter, a pattern	Every path, as with >
MCP tools	path argument of the search, agent and document list tools; path of the add document tool	As the operation that the tool calls

The document list and the search apply opposite rules when the request names no path. A document with a path therefore appears in the document list of a request without path, but in no search without path. MCP tools lists the tools of the MCP server.

Path list

GET /pipelines/{id}/paths lists the paths of the pipeline's documents and the number of documents at each path. The list counts current document versions whose classification is in the classification allow-list of the API key, and requires read permission on the pipeline.

Query parameter	Default	Description
path	>	A pattern that selects the paths to list
first	100	The maximum number of paths in the response, from 1 to 1,000. A larger value counts as 1,000.
after	None	Only the paths after this path, in byte order. The value is the next field of the previous page.
as_of	None	A point in time in microseconds since the Unix epoch. The list counts the versions that were current at that time.

The response holds data, an array of objects with the fields path and documents, ordered by the bytes of the path, and next. When the page is full, next holds the last path of the page, and a request with after set to that value returns the next page. Otherwise, next is null. Paths without a current document are not listed. An invalid path returns HTTP 400 with the message Failed to deserialize query string: <reason>.

Paths and access control

A path selects documents for a request, and grants or restricts no access. Every API key that can read a pipeline lists every path that holds a document of a classification in the key's classification allow-list, and every key that can search a pipeline can search under any path. Keys and permissions have no path setting.

Content that some users must not see is separated by classification, with the classification allow-list of each key, or by pipeline, as described in Access control. A layout that gives each user a path, such as users.<user>.notes, organizes the content of each user. The client application decides which pattern each request names, so content that one user must not see needs a classification or a separate pipeline as well.