Search API
Send a query to GitHound and receive matching GitHub files as a stream. Each match includes the repository, file path, commit, and a code preview.
The API supports literal code search. Use it to find a domain, configuration value, or distinctive phrase in indexed public code.
Run a search
Section titled “Run a search”With your API key and workspace ID configured as described below:
curl --fail-with-body --no-buffer \ "https://githoundexplore.com/api/v1/workspaces/$WORKSPACE_ID/code-search/stream" \ -H "Authorization: Bearer $GITHOUND_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"query":"example.com"}'Replace example.com with the text you want to find. Matches arrive as server-sent events: start, hit, progress, and a terminal done or error. Read through the terminal event to determine whether the results are incomplete.
Each search returns up to 100 matches and runs for up to 45 seconds. See the search endpoint reference for request fields and stream events for response examples.
Set up access
Section titled “Set up access”- Open API Access, create a key, and store its secret on your server as
GITHOUND_API_KEY. - Retrieve an owned workspace ID once using the workspace lookup endpoint and set it as
WORKSPACE_ID. The current search URL requires this ID to associate the request with your account. It does not restrict the search to that workspace’s saved results. - Run the search request above.
API execution requires Pro or another eligible account entitlement. Keys are managed in the application. See authentication and keys for eligibility and key rotation.
Handle the results
Section titled “Handle the results”- Process each
hitas it arrives. A preview is an excerpt from an indexed snapshot, not necessarily the current file. - Preserve received matches if the stream is interrupted. Mark them incomplete when no terminal event arrives.
- Check the terminal event’s coverage and completeness fields. A finished search does not establish exhaustive GitHub coverage.
- Respect
Retry-Afteron HTTP 429. Searches share your account’s daily allowance with the website.
Use stream events, limits and usage, and errors and recovery when implementing a client.
Supported requests
Section titled “Supported requests”| Method | Endpoint | Purpose |
|---|---|---|
| POST | /workspaces/{workspace_id}/code-search/stream | Search code and stream matches. |
| GET | /workspaces | Look up the ID required by the search URL. |
Base URL: https://githoundexplore.com/api/v1
API keys provide read-only literal search. Regex, Collections, advanced filters, saved-result writes, monitoring management, and relevance scoring are not available through these endpoints.
Download the OpenAPI definition. The search response uses text/event-stream; clients must support SSE rather than expecting a JSON array.