repos.grep

POST

api

repos

{repo_name}

grep

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const result = await pierre.repos.grep({
  repo_name: 'my-demo-repository',
  context: { after: 1, before: 0 },
  pagination: { limit: 50 },
  query: { case_sensitive: true, pattern: 'ephemeral branches' },
  ref: 'main',
});
console.log(result);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

result = pierre.repos.grep(
    repo_name="my-demo-repository",
    context={"after": 1, "before": 0},
    pagination={"limit": 50},
    query={"case_sensitive": True, "pattern": "ephemeral branches"},
    ref="main",
)
print(result)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
result, err := client.Repos.Grep(ctx, pierre.ReposGrepParams{
	RepoName:   "my-demo-repository",
	Context:    pierre.Value(pierre.GrepContext{After: pierre.Int(1), Before: pierre.Int(0)}),
	Pagination: pierre.Value(pierre.GrepPagination{Limit: pierre.Int(50)}),
	Query:      pierre.GrepQuery{CaseSensitive: pierre.Bool(true), Pattern: "ephemeral branches"},
	Ref:        pierre.String("main"),
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos grep \
  --repo-name my-demo-repository \
  --context.after 1 \
  --context.before 0 \
  --pagination.limit 50 \
  --query.case-sensitive true \
  --query.pattern 'ephemeral branches' \
  --ref main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/grep" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "after": 1,
      "before": 0
    },
    "pagination": {
      "limit": 50
    },
    "query": {
      "case_sensitive": true,
      "pattern": "ephemeral branches"
    },
    "ref": "main"
  }'

{
  "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"
  }
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

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.

Scopes

git:read

Path Parameters

repo_name

string

required

The repository name, for example acme/web.

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.

Example:

"main"

rev

string

deprecated

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

Response

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

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const result = await pierre.repos.grep({
  repo_name: 'my-demo-repository',
  context: { after: 1, before: 0 },
  pagination: { limit: 50 },
  query: { case_sensitive: true, pattern: 'ephemeral branches' },
  ref: 'main',
});
console.log(result);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

result = pierre.repos.grep(
    repo_name="my-demo-repository",
    context={"after": 1, "before": 0},
    pagination={"limit": 50},
    query={"case_sensitive": True, "pattern": "ephemeral branches"},
    ref="main",
)
print(result)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
result, err := client.Repos.Grep(ctx, pierre.ReposGrepParams{
	RepoName:   "my-demo-repository",
	Context:    pierre.Value(pierre.GrepContext{After: pierre.Int(1), Before: pierre.Int(0)}),
	Pagination: pierre.Value(pierre.GrepPagination{Limit: pierre.Int(50)}),
	Query:      pierre.GrepQuery{CaseSensitive: pierre.Bool(true), Pattern: "ephemeral branches"},
	Ref:        pierre.String("main"),
})
if err != nil {
	return err
}
fmt.Println(result)

pierre repos grep \
  --repo-name my-demo-repository \
  --context.after 1 \
  --context.before 0 \
  --pagination.limit 50 \
  --query.case-sensitive true \
  --query.pattern 'ephemeral branches' \
  --ref main

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/grep" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "after": 1,
      "before": 0
    },
    "pagination": {
      "limit": 50
    },
    "query": {
      "case_sensitive": true,
      "pattern": "ephemeral branches"
    },
    "ref": "main"
  }'

{
  "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"
  }
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

Authorizations

Scopes

Path Parameters

Body

Response