Grep

Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices.

JWT claims

Required scopes: git:read
Requires per repo scope: Yes

POST /api/repos/{repo_name}/grep

Grep

cURL

curl --request POST \
  --url https://api.{cluster}.code.storage/api/repos/{repo_name}/grep \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "context": {
    "after": 1,
    "before": 0
  },
  "pagination": {
    "limit": 50
  },
  "query": {
    "case_sensitive": true,
    "pattern": "ephemeral branches"
  },
  "rev": "main"
}
'

200

{
  "has_more": true,
  "incomplete_results": false,
  "matches": [
    {
      "path": "app/blog/markdown/ephemeral-branches.md"
    }
  ],
  "query": {
    "case_sensitive": true,
    "pattern": "ephemeral branches"
  },
  "repo": {
    "commit": "b003fc78805954584e1ee364a4ad39d7c79e819a",
    "ref": "main"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Path Parameters

repo_name · string · required

Repository name. Names that contain / or any other character that is not safe in a URL path segment must be URL encoded so the value occupies a single path segment. For example pierre/example is sent as pierre%2Fexample. Plain names such as example can be sent as-is. The server URL-decodes the value before resolving the repository.

Body

application/json

Search repository contents by pattern. Optional file filters, context lines, and pagination let you retrieve only the relevant slices for agents and tools.

Grep request describing the pattern, ref, filters, limits, and pagination for a repository content search.

query · object · required

Pattern configuration.

Show child attributes

context · object

Lines of context to include before and after each match.

Show child attributes

ephemeral · boolean

Whether ref should be resolved from the ephemeral namespace.

file_filters · object

Optional include and exclude filters applied before matching.

Show child attributes

limits · object

Maximum line and per-file match limits.

Show child attributes

pagination · object

Cursor-based pagination controls for large result sets.

Show child attributes

paths · string[]

Optional path prefixes used to narrow the search before pattern matching.

Repository-relative path used to scope the operation.

ref · string

Preferred branch, tag, or commit to search.

rev · string · deprecated

Deprecated: use ref. Legacy ref field retained for backwards compatibility.

Example:

"main"

Response

200

application/json

Search results for the requested pattern.

Grep results grouped per file, including the resolved ref and pagination state.

has_more · boolean · required

Whether additional matches remain.

Example:

true

incomplete_results · boolean · required

True when the result set is incomplete because the server-side output cap was reached. Matches beyond the cap exist in the repo but cannot be retrieved by paging: narrow the query (pattern, paths, file filters) or raise max_lines if it was set below the maximum. next_cursor still pages through everything collected below the cap.

Example:

false

matches · object[] · required

Files that matched the query, each with matching and context lines.

Show child attributes

next_cursor · string | null · required

Opaque cursor for the next page, if any.

query · object · required

The effective query settings used by the server.

Show child attributes

repo · object · required

Resolved repository ref and commit used for the search.

Show child attributes