GitWorld

GitWorld API

One key and one base URL for repository search across hosts and registries. GitWorld does the fan-out, normalization, scoring and caching; your code talks to one neutral model instead of integrating each host.

Quickstart
curl -H "Authorization: Bearer gw_live_…" \
  "https://gitworld.app/api/v1/search?q=vector+database&language=rust"

Send your key as Authorization: Bearer or x-api-key. Responses are JSON with snake_case fields.

Endpoints

GET/api/v1/search?q=vector+database

Ranked results merged from every host and registry GitWorld can reach, with facets and per-upstream status.

GET/api/v1/repos/{host}/{owner}/{name}

Canonical entity: identity, popularity, distribution, Health Score with factors.

GET/api/v1/repos/{host}/{owner}/{name}/health

Health Score and every factor, or an explicit null when signals are too sparse.

GET/api/v1/repos/{host}/{owner}/{name}/plan

Install/run plan inferred from real manifests, plus the runnability verdict.

GET/api/v1/repos/{host}/{owner}/{name}/alternatives

Computed similar projects, with the selection method stated in the response.

POST/api/v1/runs

Execute a repository in an ephemeral Linux sandbox. Body: {"repository":"github/owner/name"}.

GET/api/v1/runs/{id}

Run status, exit code, and the reproducible template digest it executed.

GET/api/v1/runs/{id}/logs

Server-Sent Events log stream; resumable with Last-Event-ID, or ?format=json for a snapshot.

DELETE/api/v1/runs/{id}

Stop a live run and release its sandbox.

Runs

A run executes a repository’s own recipe in an ephemeral Linux sandbox. GitWorld builds that recipe from the manifests it can actually read — image, install steps, run steps — and hashes it into a template.digest, so the same repository state always produces the same run and drift is visible.

curl -X POST -H "Authorization: Bearer gw_live_…" \
  -H "content-type: application/json" \
  -d '{"repository":"github/tiangolo/fastapi","timeout_seconds":300}' \
  "https://gitworld.app/api/v1/runs"

Returns 201 with the run, its template, and links. A repository with no runnable manifest answers 422 and says which signal was missing.

curl -N -H "Authorization: Bearer gw_live_…" \
  "https://gitworld.app/api/v1/runs/{id}/logs"

event: log
data: {"seq":4,"stream":"stdout","message":"Installing dependencies…"}

event: end
data: {"status":"succeeded","exit_code":0}

Logs stream as Server-Sent Events. Every log event carries an id, so a dropped connection resumes exactly where it stopped with Last-Event-ID or ?after=. Long runs end a connection with a reconnect event rather than truncating silently.

Bring your own sandbox

GitWorld does not own compute. Any container or microVM backend can serve runs by implementing four endpoints — the GitWorld Runner contract — and a deployment points at it with GITWORLD_RUNNER_URL and GITWORLD_RUNNER_TOKEN.

POST   /runs                   -> { id }
GET    /runs/{id}              -> { state, exit_code, error }
GET    /runs/{id}/logs?after=N -> { lines: [{ stream, message }] }
DELETE /runs/{id}

Honest limits

  • Every response carries a provenance block naming the upstreams that answered, and whether the data was cached or served from GitWorld’s labelled fallback dataset.
  • A Health Score can be null. When an upstream doesn’t expose enough signal, the API says so rather than inventing a number.
  • A run only happens when a sandbox backend is connected to the deployment. If none is, POST /api/v1/runs answers 503 and names what is missing — it never queues a run that cannot execute.
  • Runs are scoped to the key that created them. A key can read and cancel only its own runs, and browser-tier execution stays in the visitor’s workspace tab, where HTTP callers cannot reach it.