shithub Public

Watch 1 Fork 0 Star 0
markdown · 1424 bytes Raw Blame History

Search

Planned. Search over the API is not shipped yet. The web UI's /search is the only entry point today.

Planned routes

Method Path Scope
GET /api/v1/search/code None (public corpus only without repo:read); repo:read to include private.
GET /api/v1/search/repositories Same scoping.
GET /api/v1/search/issues Same scoping.
GET /api/v1/search/users None.

Query parameters:

  • q= — search query, with the same operators as Search (user docs).
  • sort= — created, updated, stars, relevance (default).
  • order= — asc, desc.
  • per_page=, cursor=.

Response shape (proposed):

{
  "total_count": 142,
  "items": [
    { /* type-dependent record */ }
  ]
}

The total is counted to a cap (10000) — for larger result sets the API returns "10000+" semantics rather than counting exactly. Consumers that need totals should narrow the query.

Visibility

Search results are filtered by the requesting PAT's user's visibility, identical to the web UI's behavior. A token cannot see a result it would not see in a browser logged in as the same user.

View source
1 # Search
2
3 > **Planned.** Search over the API is not shipped yet. The web UI's
4 > `/search` is the only entry point today.
5
6 ## Planned routes
7
8 | Method | Path | Scope |
9 |--------|-----------------------------------|--------------------------------|
10 | GET | `/api/v1/search/code` | None (public corpus only without `repo:read`); `repo:read` to include private. |
11 | GET | `/api/v1/search/repositories` | Same scoping. |
12 | GET | `/api/v1/search/issues` | Same scoping. |
13 | GET | `/api/v1/search/users` | None. |
14
15 Query parameters:
16
17 - `q=` — search query, with the same operators as
18 [Search (user docs)](../user/search.md).
19 - `sort=` — `created`, `updated`, `stars`, `relevance` (default).
20 - `order=` — `asc`, `desc`.
21 - `per_page=`, `cursor=`.
22
23 Response shape (proposed):
24
25 ```json
26 {
27 "total_count": 142,
28 "items": [
29 { /* type-dependent record */ }
30 ]
31 }
32 ```
33
34 The total is **counted to a cap** (10000) — for larger result
35 sets the API returns "10000+" semantics rather than counting
36 exactly. Consumers that need totals should narrow the query.
37
38 ## Visibility
39
40 Search results are filtered by the requesting PAT's user's
41 visibility, identical to the web UI's behavior. A token cannot
42 see a result it would not see in a browser logged in as the
43 same user.