> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reposeek.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/search

> Search open-source repositories with a natural-language query.

# POST /v1/search

Search open-source repositories and receive ranked candidates with summaries and GitHub metadata.

```text theme={null}
POST https://api.reposeek.ai/v1/search
```

## Headers

| Header          | Required | Value                       |
| --------------- | -------- | --------------------------- |
| `Authorization` | Yes      | `Bearer <REPOSEEK_API_KEY>` |
| `Content-Type`  | Yes      | `application/json`          |

## Request body

| Field     | Type    | Required | Rules                                                                               |
| --------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `query`   | string  | Yes      | Non-blank, max 1024 characters, must contain a searchable letter/digit token.       |
| `limit`   | integer | No       | Defaults to `3`; must be from `1` to `10`.                                          |
| `filters` | object  | No       | Optional repository metadata constraints. Supports `stars`, `forks`, and `license`. |

Unknown fields are rejected. There is no public `sort` or `order` field; final ordering remains owned by the reranker.

## Filters

Filters are hard eligibility constraints applied to Reposeek's indexed corpus before reranking. They narrow candidates, but they do not sort results.

| Field               | Meaning                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `filters.stars.min` | Include repos with at least this many stars. Must be at least `257`.                                             |
| `filters.stars.max` | Include repos with at most this many stars. Must be at least `257`.                                              |
| `filters.forks.min` | Include repos with at least this many forks. Must be a non-negative integer.                                     |
| `filters.forks.max` | Include repos with at most this many forks. Must be a non-negative integer.                                      |
| `filters.license`   | SPDX-style license string or array. Accepts at most 10 values. Matching is exact after trimming and lowercasing. |

Use `stars.min`, `stars.max`, `forks.min`, `forks.max`, and `license` only inside `filters`.

For range filters, `min` must be less than or equal to `max` when both are present. License filters must be a non-empty trimmed string; license arrays must be non-empty, contain only non-empty strings, and accept at most 10 values.

Unsupported fields are rejected, including unknown top-level fields, unsupported filter keys, and any public `sort` or `order` field.

Array values use OR within the same field and filters use AND across fields. Repositories with missing license metadata do not match a constrained `license` filter.

```json theme={null}
{
  "query": "local AI assistant that remembers screen activity",
  "limit": 5,
  "filters": {
    "stars": { "min": 1000 },
    "forks": { "min": 10 },
    "license": ["MIT", "Apache-2.0"]
  }
}
```

Final ordering remains owned by the reranker. If no eligible repositories match both the query and filters, the response is `"results": []`.

## curl

```bash theme={null}
curl -sS -X POST "https://api.reposeek.ai/v1/search" \
  -H "Authorization: Bearer ${REPOSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"macOS menu bar timer app swift","limit":3}'
```

<a href="https://reposeek.ai/dashboard/playground?example=macos-menu-bar-timer">Explore in API Playground</a>

Sign in to run this request from your dashboard.

## Response

```json theme={null}
{
  "request_id": "req_a1b2c3d4e5f6",
  "results": [
    {
      "rank": 1,
      "repo": "Mirix-AI/MIRIX",
      "url": "https://github.com/Mirix-AI/MIRIX",
      "score": 0.80,
      "summary": "A multi-agent personal AI assistant that builds memory from screen observation, conversations, and multimodal inputs, with local privacy-first storage.",
      "stars": 3500,
      "forks": 300,
      "license": "Apache-2.0"
    }
  ]
}
```

When reporting a CLI or API issue, include the returned `request_id`. Reposeek uses it to locate the server-side request in operational logs without exposing ranking internals in the public response body.

## Response headers

Successful searches include:

| Header          | Meaning                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------- |
| `X-Request-Id`  | Matches the JSON `request_id` and backend structured logs. Include it when reporting issues. |
| `Server-Timing` | Route-level search latency, for example `search;dur=312`.                                    |

See [search result fields](/search/results) for the full field reference.