DevGitHub search · GitHub REST

github.search

Searches GitHub repositories, code (needs GITHUB_TOKEN) or issues/PRs. details on a repository returns the README head, top-level tree and stats.

POST/v1/capabilities/github.search/execute

Charge returned per callStable

operationId: executeGithubSearch
Source: GitHub REST
Typical credits: 0 (free source)
Search deadline: 15 s server-side
Paging: page
Availability: ConfiguredChecked 2026-11-03 16:34 UTC

Cost basis

Free (60 req/h unauthenticated, 5000 with GITHUB_TOKEN). Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request body

Body of POST /v1/capabilities/github.search/execute, JSON, validated against the GithubSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of github.search
Field	Description
querystringREQUIRED	GitHub search syntax.min length 1 · max length 300
kind"repositories" \| "code" \| "issues"	Default `"repositories"`.
sortstring	stars \| forks \| updated (repositories); created \| updated \| comments (issues).min length 1 · max length 30
numinteger	Results per page (1-30).Default `10`.min 1 · max 30

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

kind: "code" needs a GitHub token in the deployment; without one the call fails with capability_unavailable.

Examples

Repos

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/github.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"fastify plugin language:typescript","kind":"repositories","sort":"stars","num":5}'

Issues

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/github.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"repo:fastify/fastify is:issue hooks","kind":"issues"}'

Record fields

Each item in results[] carries record_id and title (contract, always present) and usually url and snippet. The other keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the GithubSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. Anything else comes from the provider and may change; see stability tiers.

Record keys of github.search
Key	Note
record_idstringALWAYS	Use it with record actions on `POST /v1/follow-up`.
titlestringALWAYS	Contract key.
urlstring	Contract key; usually present.
snippetstring	Contract key; usually present.
kind"repository" \| "issue" \| "pull_request" \| "code"ALWAYS	On every record.
starsinteger	Repositories.
forksinteger	Repositories.
open_issuesinteger	Repositories.
languagestring	Repositories.
topicsstring[]	Repositories.
created_atstring	Issues and pull requests.
updated_atstring	When the source has it.
archivedboolean	Repositories.
licensestring	Repositories.
repostring	Issues and code.
numberinteger	Issues.
statestring	Issues.
authorstring	Issues.
commentsinteger	Issues.
labelsstring[]	Issues.
pathstring	Code.
matchesstring[]	Code.

Caveats

GitHub caps search at 1,000 results, so has_more turns false before the provider total.

Follow-ups

Paging: Provider page number; more fetches the next page from the source.

moreNext page of the same search. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.

updateRe-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (GithubSearchUpdateParams).

detailsREADME head, top-level files, stars/forks/issues.

Detail behaviour: Free provider lookup on first call; repeats are cached. details is a free GitHub API lookup (readme head, tree, stats).

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/github.search/execute", {
  body: {
    "query": "fastify plugin language:typescript",
    "kind": "repositories",
    "sort": "stars",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);

Recorded responseproduction · 26 Sep

Request

POST /v1/capabilities/github.search/execute

{
  "query": "fastify plugin language:typescript",
  "kind": "repositories",
  "sort": "stars",
  "num": 5
}