grep_resource

Search inside a single text resource and get back the matching lines with their line numbers — instead of reading the whole resource. This is the read counterpart to patch_resource: a large resource stays cheap to search, and the result points you straight at the lines you care about. Address it by its path — set team for a team resource.

With a credential that represents a user, omitting team targets that user's space. A userless organization credential must name a team it is bound to.

Only text resources can be searched. A binary resource (an image, a PDF, an archive) is rejected.

query is a literal substring by default. Set regex to treat it as a regular expression instead, and ignore_case to match regardless of case.

Parameters

Parameter	Type	Required	Description
path	string	Yes	The resource to search, addressed by its path.
team	string	No	The team that owns it. Omit to target the represented user's space.
query	string	Yes	What to search for — a literal substring, or a regex if regex is set.
regex	boolean	No	Treat query as a regular expression instead of a literal substring.
ignore_case	boolean	No	Match case-insensitively (default: case-sensitive).

Response

Field	Type	Description
path	string	The resource path.
matches	array	The matching lines (see below), in order.
truncated	boolean	true if there were more matches than the result cap.
version	integer	The resource's current version — pass as expected_version to a guarded edit.

Each entry in matches:

Field	Type	Description
line	integer	The 1-based line number.
text	string	The matching line (very long lines are shortened).

Example

{
	"path": "docs/api.md",
	"query": "version",
	"ignore_case": true
}

Result:

{
	"path": "docs/api.md",
	"matches": [
		{ "line": 12, "text": "version: 1.2.0" },
		{ "line": 40, "text": "Version history" }
	],
	"truncated": false,
	"version": 1
}

Errors

Each failure carries a precise code in the response. A domain rejection — a not-found, a bad query, or a capability denial — is returned as a tool result with isError: true, so the agent can read the code and self-correct; malformed arguments and server faults are JSON-RPC protocol errors.

Code	Cause	Delivered as
resource_not_found	No matching resource is visible to you — it doesn't exist, is disabled, or is out of scope.	tool error (isError)
not_a_text_resource	The resource is not a text type.	tool error (isError)
empty_query	query is empty.	tool error (isError)
invalid_regex	regex is set but the pattern doesn't compile.	tool error (isError)
team_not_found	No team with that name is bound to this credential.	tool error (isError)
capability_denied	The credential lacks the Resources capability required for this read.	tool error (isError)
personal_cannot_address_team	You used a team/ prefix (or team field) with a personal credential.	tool error (isError)
no_personal_space	This credential has no personal space — address a team instead.	tool error (isError)
resource_not_utf8	The resource is text but its stored bytes aren't valid UTF-8 — read it in the dashboard.	tool error (isError)
invalid_arguments	The arguments are missing or don't match the input schema.	protocol error (invalid_params)
internal_error	An unexpected error occurred.	protocol error (internal_error)

Notes

• Matches and version come from the same revision. If a concurrent update or deletion makes that revision unavailable during the read, the call can fail with internal_error; search again before editing.
• You can search any resource you can read — there is no separate permission. A resource you can't see (it's disabled or out of your scope) simply reads as not found.
• The result is capped at a fixed number of matching lines; truncated tells you when more matched than were returned. Narrow your query to see the rest.
• Use the returned line numbers directly with patch_resource to edit what you found.
• Searching a resource counts as one tool call against your plan's tool-invocation allowance.