# Search g1t

> Search all of g1t: repositories (name, description, topics, README), code on default branches (file names and contents), issues, pull requests, people and workspaces.

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/search</code></div>

Covers everything public, and private content in workspaces you belong to; signed out, public only. Write words, "exact phrases", -words to leave out, and qualifiers: repo:owner/name, org:workspace, language:rust, path:src/ (a glob with *), is:issue, is:pr, is:open, is:closed, is:merged, author:username, label:bug. type picks the kind of results (repositories, code, issues, pulls or people); without it, the qualifiers decide. Returns one page of results with the matches highlighted, code with line numbers, and how many there are of each kind.

`q` takes words, `"exact phrases"`, `-words` to leave out, and qualifiers: `repo:owner/name`, `org:` (or `workspace:`), `language:`, `path:` (a glob when it has `*`), `is:issue`, `is:pr`, `is:open`, `is:closed`, `is:merged`, `is:draft`, `is:public`, `is:private`, `author:` and `label:`; most can be left out with a leading `-`, as in `-label:wontfix`. `type` is `repositories`, `code`, `issues`, `pulls` or `people`; without it, `path:` means code, `is:pr` pull requests, `is:open`, `author:` or `label:` issues, and anything else repositories. `counts` says how many results each type has, up to 1,000. Each result's `snippet` (or, for code, each of its `lines`) is a list of parts, `highlight` true where the query matched. Code is searched on default branches and needs a word of three characters or more, unless the query names a `repo:`. Public content is returned to anyone, without a token; private content only to people who can read it (members of its workspace, and people given a role on the repository), checked when the search runs, so a repository made private, or a role taken away, stops appearing at once. A g1t agent's token can search too.

- **Authentication:** Optional. Public data can be read without a token; send one to see what is private.
- **MCP tool:** [`search`](/reference/mcp/#search) with `action` `code`, and the same inputs
- **Scope:** An access token needs [`repo:read`](/guides/authentication/#scopes).

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | What to look for: words, "phrases" and qualifiers, such as parse_query language:rust repo:acme/web. |
| `type` | string | No | Which kind of results. Worked out from the qualifiers if not given: path: means code, is:pr pull requests, is:open or label: issues, otherwise repositories. One of `repositories`, `code`, `issues`, `pulls`, `people`. |
| `page` | integer | No | From 1; at most 50. |
| `per_page` | integer | No | At most 50; 20 if not given. |

## Example request

```sh
curl "https://api.g1t.sh/search?q=parse_query+language%3Arust+repo%3Aacme%2Fweb&type=code" \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "query": "parse_query repo:acme/web language:rust",
  "type": "code",
  "counts": {
    "repositories": 0,
    "code": 2,
    "issues": 0,
    "pulls": 0,
    "people": 0
  },
  "page": 1,
  "per_page": 20,
  "more": false,
  "hits": [
    {
      "kind": "code",
      "title": "src/search/query.rs",
      "url": "/acme/web/blob/main/src/search/query.rs#L42",
      "repo": "acme/web",
      "private": false,
      "description": null,
      "snippet": [],
      "lines": [
        {
          "number": 41,
          "parts": [
            {
              "text": "/// Reads a query typed into the search box.",
              "highlight": false
            }
          ]
        },
        {
          "number": 42,
          "parts": [
            {
              "text": "pub fn ",
              "highlight": false
            },
            {
              "text": "parse_query",
              "highlight": true
            },
            {
              "text": "(text: &str) -> Query {",
              "highlight": false
            }
          ]
        },
        {
          "number": 43,
          "parts": [
            {
              "text": "    let mut query = Query::default();",
              "highlight": false
            }
          ]
        }
      ],
      "path": "src/search/query.rs",
      "language": "rust",
      "ref": "main",
      "number": null,
      "state": null,
      "author": null,
      "labels": [],
      "topics": [],
      "slug": null,
      "avatar": null,
      "updated_at": null
    }
  ],
  "notes": []
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |