# Search the context hub

> One search across a workspace's context hub: its catalog (projects, apps, APIs, packages, languages, owners, environments, integrations, docs), the text of its docs, its issues and pull requests, and, for members and g1t's agents, its kept memory.

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/workspaces/{workspace}/context/search</code></div>

Results are ranked by meaning, each labelled with its kind, where it came from, who wrote it and how fresh it is; matching words answers when meaning cannot. Give the workspace, or a repository in it. Narrow with project (a project's slug) and kinds. Reads only what you may see: memory and private projects are for members.

Give `workspace`, or `repo` as `owner/name` for its workspace. `kinds` narrows to some of `project`, `app`, `api`, `package`, `language`, `owner`, `environment`, `integration`, `doc`, `memory`, `issue` and `pull`; in a URL, comma-separated. `mode` is `text` when the search index could not answer and words were matched instead. Memory is returned only to members of the workspace and its agents; anything from a private project, only to those who can read it (members, unless the base permission is None, and people given a role on its repository). A g1t agent searches its own workspace only.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`search_context`](/reference/mcp/), with the same inputs

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's slug, e.g. "flagon-io". |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | What you want to know, in words: "how do we deploy the api", "who owns billing". |
| `project` | string | No | Only what is about this project, by its slug. |
| `kinds` | array of strings | No | Only these kinds. All of them if not given. One of `project`, `app`, `api`, `package`, `language`, `owner`, `environment`, `integration`, `doc`, `memory`, `issue`, `pull`. |
| `limit` | integer | No | At most 50; 20 if not given. |

## Example request

```sh
curl "https://api.g1t.sh/workspaces/acme/context/search?q=how+do+we+run+the+web+tests&project=web" \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "query": "how do we run the web tests",
  "mode": "semantic",
  "hits": [
    {
      "kind": "memory",
      "id": "mem_01m4a0c2b7k3f9d1e5g8h2j6k4",
      "title": "Gotcha",
      "snippet": "The date tests fail unless TZ=UTC.",
      "project": "web",
      "url": "/acme/web/memory",
      "score": 0.82,
      "source": "AGENTS.md",
      "by": "g1t",
      "updated_at": "2026-10-04T21:10:02.000Z"
    },
    {
      "kind": "doc",
      "id": "ent_5f0c2a9e41d7b3c86a1e2f40:2",
      "title": "Web (README.md)",
      "snippet": "## Testing Run npm test. The end-to-end tests need the api running locally…",
      "project": "web",
      "url": "/acme/web/blob/main/README.md",
      "score": 0.77,
      "source": "README.md",
      "by": null,
      "updated_at": "2026-10-04T20:58:41.000Z"
    },
    {
      "kind": "project",
      "id": "ent_9b1d6f0a2c3e4b5d6e7f8a9b",
      "title": "web",
      "snippet": "The storefront. Written in TypeScript. Packages: @acme/web. Uses api. Owned by ana.",
      "project": "web",
      "url": "/acme/web",
      "score": 0.71,
      "source": "catalog",
      "by": null,
      "updated_at": "2026-10-04T20:58:41.000Z"
    }
  ]
}
```

## 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. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |