> ## 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. # 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 Deprecated: Use `/api/repos/{repo_name}/grep` instead. ## OpenAPI ````yaml https://api.pierre.code.storage/api/openapi.json post /api/v1/repos/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`. 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. title: code.storage version: 1.0.0 servers: - description: Code Storage tenant cluster url: https://api.{cluster}.code.storage variables: cluster: default: cluster description: >- Tenant cluster identifier (e.g. pierre-dev, pierre-staging, pierre-prod). security: [] tags: - description: Create, inspect, update, delete, and synchronise repositories. 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: >- Trigger upstream synchronisation for repositories backed by an external source. name: Sync - description: Manage generic HTTPS Git credentials for non-GitHub upstreams. name: Credentials paths: /api/v1/repos/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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/grep` instead. operationId: grep_legacy requestBody: content: application/json: example: context: after: 1 before: 0 pagination: limit: 50 query: case_sensitive: true pattern: ephemeral branches rev: main schema: additionalProperties: false description: >- Grep request describing the pattern, ref, filters, limits, and pagination for a repository content search. properties: context: additionalProperties: false description: Lines of context to include 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 ephemeral: description: Whether ref should be resolved from the ephemeral namespace. type: boolean file_filters: additionalProperties: false description: >- Optional include and exclude filters applied before matching. 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 limits: additionalProperties: false description: Maximum line and per-file match limits. 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 pagination: additionalProperties: false description: Cursor-based pagination controls for large result sets. 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 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: additionalProperties: false description: Pattern configuration. 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 ref: description: Preferred branch, tag, or commit to search. type: string rev: description: >- Legacy ref field retained for backwards compatibility. Prefer the ref field for new callers. examples: - main type: string required: - rev - query type: object 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 matches: - path: app/blog/markdown/ephemeral-branches.md query: case_sensitive: true pattern: ephemeral branches repo: commit: b003fc78805954584e1ee364a4ad39d7c79e819a ref: main schema: 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 matches: description: >- Files that matched the query, each with matching and context lines. items: additionalProperties: false description: Matches grouped under a single file path. properties: lines: description: >- Lines returned for the match, including optional context lines. items: 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 type: array path: description: Repository-relative file path that matched. examples: - app/blog/markdown/ephemeral-branches.md type: string required: - path - lines type: object type: array next_cursor: description: Opaque cursor for the next page, if any. type: - string - 'null' query: additionalProperties: false description: The effective query settings used by the server. 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 repo: additionalProperties: false description: Resolved repository ref and commit used for the search. 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 required: - query - repo - matches - next_cursor - has_more type: object 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: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Bad Request '401': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Unauthorized '403': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Forbidden '404': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Not Found '409': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Conflict '429': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Too Many Requests '500': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Internal Server Error '503': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: 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 type: object description: Service Unavailable deprecated: true security: - bearerAuth: [] components: securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ````