> ## Documentation Index > Fetch the complete documentation index at: https://code.storage/docs/llms.txt > Use this file to discover all available pages before exploring further. # repos.grep > Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository. ## OpenAPI ````yaml openapi.json POST /api/repos/{repo_name}/grep openapi: 3.1.0 info: description: >- The Code Storage HTTP API exposes repository management, Git reads, and write workflows over plain HTTPS. ## Authentication Send a signed JWT in the `Authorization: Bearer ` header on every request. - Organisation-scoped endpoints such as `GET /api/repos` require organisation scopes like `org:read` - Repository-scoped endpoints require a JWT whose `repo` claim names the target repository - Write operations require the relevant scope such as `git:write` or `repo:write` ## Pagination List endpoints use cursor-based pagination. - `cursor` is an opaque token returned by the previous response - `limit` defaults to `20` and is capped per endpoint - `has_more` tells you whether another request is available - `next_cursor` becomes the next `cursor` value ## Paths Preferred routes use the shorter `/api/...` form. Legacy `/api/v1/...` aliases remain documented where they are still supported and are marked as deprecated when a preferred route exists. ## Repository names in paths - Names containing `/` (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` becomes `pierre%2Fexample` and the request URL is `/api/repos/pierre%2Fexample/...`. - Plain names that contain only URL-safe characters can be sent as-is: `/api/repos/dotfiles/...`. - The server URL-decodes the value before resolving the repository, so double-encoding is not required. ## Errors Most endpoints return RFC 9457-compatible problem details under `application/problem+json`, with a legacy `error` field mirrored from `detail`. Each problem body has a stable, snake_case `code`. Branch on `code`, not on `detail`. The Error codes section lists the values. A `400 Bad Request` response for a request body can name the invalid fields in `invalid_params`. Each item has the dotted path of the field in `name`, for example `deployment.production_branch`, and the rule that the value breaks in `reason`. A `429 Too Many Requests` response carries the current IETF `RateLimit` service-limit field and `Retry-After`. `RateLimit` reports immediately available quota (`r`) and its effective window in seconds (`t`); `Retry-After` is the minimum delay and takes precedence. The gateway's capacity is dynamic, so it does not advertise a fixed `RateLimit-Policy` on successful responses. Streaming commit and note workflows may return operation-specific failure bodies so callers can inspect partial results, branch state, or workflow status without parsing generic error strings. ## Error codes Each problem body has a stable `code`. Each status has a generic code. A specific code replaces it when the caller must take a different action. New codes can be added. Treat an unknown code as the generic code for its status. Generic codes: `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `request_timeout` (408), `conflict` (409), `precondition_failed` (412), `payload_too_large` (413), `unprocessable_entity` (422), `rate_limited` (429), `request_canceled` (499), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Any other status uses its status text in snake_case. Specific codes: - `authentication_unavailable` (403): the server cannot verify credentials now; retry. - `insufficient_scope` (403): the token does not have a scope that the operation requires. - `repo_claim_missing` (400): the token has no `repo` claim. - `repo_name_mismatch` (400): the request `repo_name` does not match the token `repo` claim. - `route_not_found` (404): no API route matches the path. - `repository_not_found` (404): the repository does not exist or the token cannot access it. - `repository_deleted` (409): the repository is already deleted. - `repository_thawing` (409): the repository is being restored from cold storage; retry after `Retry-After`. - `sync_in_progress` (409): an upstream sync is in progress; retry. - `upstream_already_configured` (409): the repository already has an upstream. - `branch_not_found` (404): the branch does not exist. - `ref_not_found` (404): the ref or revision does not exist. - `merge_conflict` (409): the merge has file conflicts. - `ref_guard_failed` (409): a ref guard such as `expected_target_sha` does not match the ref; `guard` names it and `current_sha` is the commit of the ref. - `credential_not_found` (404): the Git credential does not exist. - `credential_exists` (409): the repository already has a Git credential. - `github_app_not_configured` (412): no GitHub App is set up for the organization, or the GitHub App of the repository has no usable private key. - `github_repository_inaccessible` (412, or the 4xx status from the upstream): GitHub does not give access to the upstream repository. - `hosting_not_enabled` (403): hosting is not enabled for the organization. - `hosting_project_not_found` (404): the repository has no hosting project. - `deployment_not_found` (404): the deployment does not exist. - `deployment_project_name_in_use` (409): another repository uses the hosting project name. - `idempotency_key_reused` (422): the idempotency key belongs to a different request. title: code.storage version: 1.0.0 servers: - description: Code Storage API host for your organization url: https://api.{org}.code.storage variables: org: default: your-org description: >- The subdomain of your API host. It is usually your organization name. The organization settings page in the dashboard shows your exact API host. security: [] tags: - description: >- Create, inspect, update, delete, and synchronise repositories, including upstream pull-sync and generic HTTPS Git credentials for non-GitHub upstreams. name: Repositories - description: Create, delete, list, and compare branches. name: Branches - description: >- Read commit metadata and diffs, or create commits without a local Git client. name: Commits - description: >- Read repository trees, file contents, archives, and server-side search results. name: Files - description: List, create, and delete Git tags. name: Tags - description: Attach and retrieve Git notes for commits or other Git objects. name: Notes - description: >- Read metadata about the Code Storage cluster that serves your organisation, such as its cloud location and inbound IP addresses. name: Organization paths: /api/repos/{repo_name}/grep: post: tags: - Files summary: Grep description: >- Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository. operationId: repos-grep parameters: - description: The repository name, for example `acme/web`. example: my-demo-repository in: path name: repo_name required: true schema: type: string requestBody: content: application/json: example: context: after: 1 before: 0 pagination: limit: 50 query: case_sensitive: true pattern: ephemeral branches ref: main schema: $ref: '#/components/schemas/ReposGrepRequest' description: >- Search repository contents by pattern. Optional file filters, context lines, and pagination let you retrieve only the relevant slices for agents and tools. required: true responses: '200': content: application/json: example: 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 schema: $ref: '#/components/schemas/ReposGrepResponse' description: Search results for the requested pattern. headers: X-Cache: description: Indicates grep cache status (`HIT` or `MISS`). schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Conflict '429': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Too Many Requests headers: RateLimit: description: >- Current IETF service-limit field. `r=0` means no request is immediately available; `t` is the effective window in seconds before capacity is expected to return. schema: type: string Retry-After: description: >- Minimum delay before retrying, expressed as seconds or an HTTP date. This value takes precedence over the `RateLimit` effective window. schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: Service Unavailable headers: Retry-After: description: Minimum delay in seconds before retrying. schema: type: string security: - bearerAuth: - git:read x-codeSamples: - lang: typescript label: TypeScript source: |- 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); - lang: python label: Python source: |- 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) - lang: go label: Go source: "import (\n\t\"context\"\n\t\"fmt\"\n\n\tpierre \"github.com/pierrecomputer/sdk/go\"\n)\n\nctx := context.Background()\n// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.\nclient, err := pierre.NewClient()\nif err != nil {\n\treturn err\n}\nresult, err := client.Repos.Grep(ctx, pierre.ReposGrepParams{\n\tRepoName: \"my-demo-repository\",\n\tContext: pierre.Value(pierre.GrepContext{After: pierre.Int(1), Before: pierre.Int(0)}),\n\tPagination: pierre.Value(pierre.GrepPagination{Limit: pierre.Int(50)}),\n\tQuery: pierre.GrepQuery{CaseSensitive: pierre.Bool(true), Pattern: \"ephemeral branches\"},\n\tRef: pierre.String(\"main\"),\n})\nif err != nil {\n\treturn err\n}\nfmt.Println(result)" - lang: cli label: CLI source: |- 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 - lang: bash label: cURL source: |- 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" }' components: schemas: ReposGrepRequest: additionalProperties: false description: >- Grep request describing the pattern, ref, filters, limits, and pagination for a repository content search. properties: context: $ref: '#/components/schemas/GrepContext' description: Lines of context to include before and after each match. ephemeral: description: Whether ref should be resolved from the ephemeral namespace. type: boolean file_filters: $ref: '#/components/schemas/GrepFileFilters' description: Optional include and exclude filters applied before matching. limits: $ref: '#/components/schemas/GrepLimits' description: Maximum line and per-file match limits. pagination: $ref: '#/components/schemas/GrepPagination' description: Cursor-based pagination controls for large result sets. paths: description: >- Optional path prefixes used to narrow the search before pattern matching. items: description: Repository-relative path used to scope the operation. type: string type: array query: $ref: '#/components/schemas/GrepQuery' description: Pattern configuration. ref: description: Preferred branch, tag, or commit to search. examples: - main type: string rev: deprecated: true description: >- Deprecated: use ref. Legacy ref field retained for backwards compatibility. type: string required: - query type: object ReposGrepResponse: additionalProperties: false description: >- Grep results grouped per file, including the resolved ref and pagination state. properties: has_more: description: Whether additional matches remain. examples: - true type: boolean incomplete_results: description: >- 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. examples: - false type: boolean matches: description: Files that matched the query, each with matching and context lines. items: $ref: '#/components/schemas/GrepFileMatch' type: array next_cursor: description: Opaque cursor for the next page, if any. type: - string - 'null' query: $ref: '#/components/schemas/GrepResolvedQuery' description: The effective query settings used by the server. repo: $ref: '#/components/schemas/GrepResolvedRef' description: Resolved repository ref and commit used for the search. required: - query - repo - matches - next_cursor - has_more - incomplete_results type: object ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - properties: invalid_params: description: >- The invalid fields of the request body, one item for each field. The response leaves it out when the server cannot name the field, for example when the body is not valid JSON. items: $ref: '#/components/schemas/InvalidParam' type: array type: object description: >- Problem details of a request body that is not valid. `invalid_params` names each invalid field. type: object ProblemDetails: description: >- RFC 9457-compatible problem details payload describing the error response. properties: code: description: >- A stable, machine-readable error code in snake_case. Branch on `code`, not on `detail`. The API description lists the codes. type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status - code type: object GrepContext: additionalProperties: false description: Number of context lines to return before and after each match. properties: after: description: Number of lines to include after each match. examples: - 1 format: int32 type: integer before: description: Number of lines to include before each match. examples: - 0 format: int32 type: integer type: object GrepFileFilters: additionalProperties: false description: Glob and extension filters that select the files to search. properties: exclude_globs: description: Glob patterns for files to exclude. items: description: Glob pattern such as `node_modules/**`. type: string type: array extension_filters: description: File extensions to filter by (e.g. [".js", ".py"]). items: description: File extension to match, including the leading dot (e.g. `.js`). type: string type: array include_globs: description: Glob patterns for files to include. items: description: Glob pattern such as `src/**/*.go`. type: string type: array type: object GrepLimits: additionalProperties: false description: >- Limits on the total lines and on the matches for each file in a grep response. properties: max_lines: description: Maximum total lines to return (default 2000, max 2000). format: int32 type: integer max_matches_per_file: description: Maximum matches returned per file (default 200). format: int32 type: integer type: object GrepPagination: additionalProperties: false description: Cursor and page size for grep matches. properties: cursor: description: Pagination cursor returned by a previous grep response. type: string limit: description: Maximum number of matches to return (default 200). examples: - 50 format: int32 type: integer type: object GrepQuery: additionalProperties: false description: Pattern to search for, and whether the search is case-sensitive. properties: case_sensitive: default: true description: Defaults to true when omitted. examples: - true type: boolean pattern: description: Regular expression or literal pattern to search for. examples: - ephemeral branches type: string required: - pattern type: object GrepFileMatch: additionalProperties: false description: Matches grouped under a single file path. properties: lines: description: Lines returned for the match, including optional context lines. items: $ref: '#/components/schemas/GrepLine' type: array path: description: Repository-relative file path that matched. examples: - app/blog/markdown/ephemeral-branches.md type: string required: - path - lines type: object GrepResolvedQuery: additionalProperties: false description: Query settings that the server used for the search. properties: case_sensitive: description: Echoed case-sensitivity setting. examples: - true type: boolean pattern: description: Echoed pattern that was searched. examples: - ephemeral branches type: string required: - pattern - case_sensitive type: object GrepResolvedRef: additionalProperties: false description: Ref and resolved commit that the search ran against. properties: commit: description: Resolved commit SHA the grep ran against. examples: - b003fc78805954584e1ee364a4ad39d7c79e819a type: string ref: description: Ref that was grepped. examples: - main type: string required: - ref - commit type: object InvalidParam: additionalProperties: false description: One invalid field of the request body. properties: name: description: Dotted wire path of the field. examples: - deployment.production_branch type: string reason: description: The rule that the value breaks. examples: - exceeds 255 characters type: string required: - name - reason type: object GrepLine: additionalProperties: false description: >- Single line returned by grep, either a match or a surrounding context line. properties: line_number: description: Line number in the file. format: int32 type: integer text: description: Line text content. type: string type: description: >- match for lines satisfying the pattern, or context for surrounding context lines. type: string required: - line_number - text - type type: object securitySchemes: bearerAuth: bearerFormat: JWT description: >- 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. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.