---
title: "On-demand GitHub source materialization"
method: POST
path: "/lookups"
tags: ["Lookups"]
---

# On-demand GitHub source materialization

`POST /lookups`

Resolves a GitHub `org/repo` coordinate to a registry source. Idempotent — if the source already exists, returns it with `status: "existing"`; otherwise probes GitHub, inserts a hidden `on_demand` source row (and a new `on_demand` org when no curated org claims the segment), and ingests up to 100 releases.

Negative results (`not_found`, `empty`) are cached in KV (24h and 6h respectively) so repeat probes don't re-hit GitHub. `deferred` outcomes (rate-limit, 5xx) are not cached and let the next cron pass retry.

Body requires `provider: "github"` — other providers are explicitly rejected, not silently accepted. Coordinate must match `{org}/{repo}` (case-insensitive; URLs are deduped via `LOWER(sources.url)`).

## Response `200`

Lookup result. Inspect `status` to disambiguate outcomes.

- object
  - `status` 'indexed' | 'existing' | 'empty' | 'not_found' | 'deferred', required
  - `source` object
    - `id` string, required
    - `slug` string, required
    - `name` string, required
    - `type` string, required
    - `url` string, required
    - `orgId` string, nullable, required
    - `productId` string, nullable, required
    - `isHidden` boolean, nullable
    - `discovery` 'curated' | 'agent' | 'on_demand'
    - `metadata` string, nullable, required
    - `stars` integer, nullable
    - `starsFetchedAt` string, nullable
    - `createdAt` string
  - `releases` object[]
    - `id` string, required
    - `sourceId` string, required
    - `version` string, nullable, required
    - `title` string, required
    - `url` string, nullable, required
    - `publishedAt` string, nullable, required
  - `relatedOrg` object, nullable, required
    - `org` object, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `sources` object[], required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
      - `url` string, required

## Other responses

- `400` — Missing JSON body, unsupported provider, or malformed coordinate

---

[API](https://skmtc.net/releases/apis/releases-api.md) · [All operations](https://skmtc.net/releases/apis/releases-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/releases/releases-api/revisions/168e32061f53/schema)