Search documentation, code and symbols

Search documentation, source code, and symbols across packages, public repositories, and documentation sites. Results include matching text and source locations you can use to read the original page or file.

Use this endpoint to discover relevant documentation and implementations across projects. Searches can return while indexing or searching is still in progress; use GET /v1/searches/{search_ref} to retrieve subsequent results and status.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`results`	Matching items, their text, relevance scores, source locations, and coverage information.	Yes
`results.highlights`	Highlight locations within result titles and summaries. Also includes `results`.	No
`results.*`	Results and highlights together.	No
`sources`	Source status, applied filters, coverage, and suggested documentation sites.	No
`progress`	Search request details, readiness counts, and available or suggested versions and refs.	No

POST

searches

Search documentation, code and symbols

curl --request POST \
  --url https://api.githits.dev/v1/searches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "limit": 10,
  "query": "name:run",
  "sources": [
    "code",
    "symbol"
  ],
  "targets": [
    {
      "name": "serde",
      "registry": "crates"
    }
  ],
  "wait_timeout_ms": 20000
}
'

import requests

url = "https://api.githits.dev/v1/searches"

payload = {
    "limit": 10,
    "query": "name:run",
    "sources": ["code", "symbol"],
    "targets": [
        {
            "name": "serde",
            "registry": "crates"
        }
    ],
    "wait_timeout_ms": 20000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    limit: 10,
    query: 'name:run',
    sources: ['code', 'symbol'],
    targets: [{name: 'serde', registry: 'crates'}],
    wait_timeout_ms: 20000
  })
};

fetch('https://api.githits.dev/v1/searches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/searches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'limit' => 10,
    'query' => 'name:run',
    'sources' => [
        'code',
        'symbol'
    ],
    'targets' => [
        [
                'name' => 'serde',
                'registry' => 'crates'
        ]
    ],
    'wait_timeout_ms' => 20000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/searches"

	payload := strings.NewReader("{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/searches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/searches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}"

response = http.request(request)
puts response.read_body

{
  "completed": false,
  "expires_at": null,
  "query_warnings": [],
  "result": null,
  "search_ref": "opaque-search-ref",
  "selected_fields": [
    "results"
  ],
  "status": "pending",
  "targets": [
    {
      "coverage": null,
      "freshness": null,
      "indexing_ref": null,
      "requested": "site:example.org/docs",
      "resolved_requested": "site:example.org/docs",
      "served": null,
      "target_resolution": null
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created.

Query Parameters

fields

string

default:results

Comma-separated results/results.highlights/results.*/sources/progress; default results, 2048 decoded bytes. No arbitrary leaf masks.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

Maximum string length: 2048

Body

application/json

Strict initial search input; selectors are parsed by HTTP before execution.

query

string

required

Nonblank query, trimmed once. Qualifiers and boolean/phrase syntax are parsed upstream.

Minimum string length: 1

targets

object[]

required

One through twenty structured targets. Exact normalized duplicates are removed.

Required array length: 1 - 20 elements

Exactly one addressing mode; unrelated keys, including null keys, are rejected.

Option 1
Option 2
Option 3

Show child attributes

allow_partial_results

boolean

default:false

Permit a served subset of runnable pairs; false keeps runnable-pair atomicity even during background refresh.

filters

null | object

Omission/null means no structured filters. Use upstream name:/lang [blocked]: query qualifiers for those capabilities.

Show child attributes

limit

integer<int32>

default:10

Result page cap, 1..100. This does not bound all upstream preparation work.

Required range: 1 <= x <= 100

offset

integer<int32>

default:0

Nonnegative offset. A later page requires a fresh initial search.

Required range: 0 <= x <= 2147483647

sources

enum<string>[] | null

Omission/null means AUTO; explicit docs/code/symbol lists must be nonempty. AUTO is not an explicit selector.

Content sources to search. Omission selects documentation and code for packages or repositories, and documentation for sites.

Available options:

docs,

code,

symbol

wait_timeout_ms

integer<int32>

default:20000

One upstream wait, 0..60000 ms; total transport deadline also includes configured request budget.

Required range: 0 <= x <= 60000

Response

Source-qualified immediate, interim or terminal observation

One canonical source observation; a reference does not imply active work.

completed

boolean

required

Source POST completion flag; GET is true exactly for completed status. Other terminal statuses remain false.

expires_at

string | null

required

Source expiration timestamp, not a gateway retention guarantee or exact 410 boundary.

query_warnings

string[]

required

Parser warnings from the result or inline progress, never inferred from query text.

result

null | object

required

Latest complete page; null when results is unselected or no page is available. Inspect selected_fields.

Show child attributes

search_ref

string | null

required

Effective-user-owned opaque reference; null for an immediate unreferenced result.

selected_fields

enum<string>[]

required

Canonical expanded selected groups in stable order; disambiguates unselected result:null.

Atomic evidence groups, independent of the transport protocol.

Available options:

results,

results.highlights,

sources,

progress

status

null | enum<string>

required

Explicit source session state, null when the initial operation supplies none.

Available options:

pending,

indexing,

searching,

completed,

deferred,

timeout,

failed

targets

object[] | null

required

Concise readiness/provenance supplied by inline progress; null when absent.

Show child attributes

progress

null | object

Omitted when unselected; null when selected without inline progress.

Show child attributes

sources

null | object

Omitted when unselected; null when selected without a source snapshot.

Show child attributes

⌘I

Search documentation, code and symbols

curl --request POST \
  --url https://api.githits.dev/v1/searches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "limit": 10,
  "query": "name:run",
  "sources": [
    "code",
    "symbol"
  ],
  "targets": [
    {
      "name": "serde",
      "registry": "crates"
    }
  ],
  "wait_timeout_ms": 20000
}
'

import requests

url = "https://api.githits.dev/v1/searches"

payload = {
    "limit": 10,
    "query": "name:run",
    "sources": ["code", "symbol"],
    "targets": [
        {
            "name": "serde",
            "registry": "crates"
        }
    ],
    "wait_timeout_ms": 20000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    limit: 10,
    query: 'name:run',
    sources: ['code', 'symbol'],
    targets: [{name: 'serde', registry: 'crates'}],
    wait_timeout_ms: 20000
  })
};

fetch('https://api.githits.dev/v1/searches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.githits.dev/v1/searches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'limit' => 10,
    'query' => 'name:run',
    'sources' => [
        'code',
        'symbol'
    ],
    'targets' => [
        [
                'name' => 'serde',
                'registry' => 'crates'
        ]
    ],
    'wait_timeout_ms' => 20000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.githits.dev/v1/searches"

	payload := strings.NewReader("{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.githits.dev/v1/searches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.githits.dev/v1/searches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"limit\": 10,\n  \"query\": \"name:run\",\n  \"sources\": [\n    \"code\",\n    \"symbol\"\n  ],\n  \"targets\": [\n    {\n      \"name\": \"serde\",\n      \"registry\": \"crates\"\n    }\n  ],\n  \"wait_timeout_ms\": 20000\n}"

response = http.request(request)
puts response.read_body

{
  "completed": false,
  "expires_at": null,
  "query_warnings": [],
  "result": null,
  "search_ref": "opaque-search-ref",
  "selected_fields": [
    "results"
  ],
  "status": "pending",
  "targets": [
    {
      "coverage": null,
      "freshness": null,
      "indexing_ref": null,
      "requested": "site:example.org/docs",
      "resolved_requested": "site:example.org/docs",
      "served": null,
      "target_resolution": null
    }
  ]
}

Get started

v1 reference

Search documentation, code and symbols

Selector catalogue

Authorizations

Headers

Query Parameters

Body

Response