---
title: "Find alternatives for a project from a structured JSON body."
method: POST
path: "/api/alternatives"
---

# Find alternatives for a project from a structured JSON body.

`POST /api/alternatives`

## Request

- Base URL: `https://git.top`
- URL: `https://git.top/api/alternatives`
- Auth: none declared

## Query parameters

- `require_d1` string

## Request body

- AlternativesRequest
  - `project_id` string, required
  - `projectId` string
  - `repo` string
  - `limit` integer

## Response `200`

Alternative project list with summary, stats, next_actions, comparison_links, similarity scores, and match signals

- AlternativesResponse
  - `project` ProjectCard, required: Compact project card used in search, recommendations, comparison, alternatives, and related project lists.
    - `project_id` string, required
    - `repo` string, required
    - `name` string, required
    - `github_url` string
    - `homepage_url` string, nullable
    - `language` string, nullable
    - `license` string, nullable
    - `project_kind` 'project' | 'collection'
    - `collection_metadata` object
    - `category` string[]
    - `tags` string[]
    - `description` string
    - `overview` string
    - `deployments` string[]
    - `difficulty` string
    - `cloudflare_ready` boolean
    - `git_top_score` number
    - `quality_score` number
    - `agent_score` number
    - `score` number
    - `classification` object
    - `quality_signal_confidence` QualitySignalConfidence: Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.
      - `stars_30d_delta` 'snapshot' | 'estimated'
      - `stars_30d_window_days` integer
      - `commits_30d` 'complete' | 'partial' | 'unknown'
      - `releases_180d` 'complete' | 'partial' | 'unknown'
      - `contributors_90d` 'complete' | 'partial' | 'unknown'
    - `verification` VerificationPackage: Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.
      - `schema_version` 'git-top.verification.v1', required
      - `overall_status` 'complete' | 'partial' | 'unverified', required
      - `observed_at` string, date-time, nullable, required
      - `signals` object, required
        - `activity` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `license` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `documentation` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `runtime` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `install` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `security` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `mcp` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
      - `coverage` object, required
        - `observed` integer, required
        - `inferred` integer, required
        - `not_run` integer, required
        - `unknown` integer, required
      - `next_steps` string[], required
    - `summary` ProjectSummary
      - `tl_dr` string, required: One-sentence project overview for agents.
      - `purpose` string, required: Longer agent-facing project purpose.
      - `install` string, nullable: Conservative install or setup hint when Git.Top can infer one.
      - `inputs` string[], required
      - `outputs` string[], required
      - `good_for` string[], required
      - `not_good_for` string[], required
      - `deployment` string[], required
      - `alternatives` object[], required
        - `repo` string, required
        - `reason` string, required
    - `evidence` NormalizedEvidence: Normalized evidence package for agent citation and caveat handling.
      - `classification` object
      - `quality_signal_confidence` QualitySignalConfidence: Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.
        - `stars_30d_delta` 'snapshot' | 'estimated'
        - `stars_30d_window_days` integer
        - `commits_30d` 'complete' | 'partial' | 'unknown'
        - `releases_180d` 'complete' | 'partial' | 'unknown'
        - `contributors_90d` 'complete' | 'partial' | 'unknown'
      - `verification` VerificationPackage: Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.
        - `schema_version` 'git-top.verification.v1', required
        - `overall_status` 'complete' | 'partial' | 'unverified', required
        - `observed_at` string, date-time, nullable, required
        - `signals` object, required
          - `activity` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `license` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `documentation` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `runtime` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `install` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `security` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `mcp` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
        - `coverage` object, required
          - `observed` integer, required
          - `inferred` integer, required
          - `not_run` integer, required
          - `unknown` integer, required
        - `next_steps` string[], required
      - `source_fields` string[]
      - `caveats` string[]
      - `confidence_reason` string
      - `last_verified_at` string, date-time, nullable
    - `caveats` string[]
    - `confidence_reason` string
    - `source_fields` string[]
    - `last_verified_at` string, date-time, nullable
  - `resolved_from` object
  - `summary` string
  - `stats` object
  - `alternatives` object[]
  - `alternative_matches` AlternativeMatch[], required
    - `project_id` string, required
    - `repo` string, required
    - `name` string, required
    - `github_url` string
    - `homepage_url` string, nullable
    - `language` string, nullable
    - `license` string, nullable
    - `project_kind` 'project' | 'collection'
    - `collection_metadata` object
    - `category` string[]
    - `tags` string[]
    - `description` string
    - `overview` string
    - `deployments` string[]
    - `difficulty` string
    - `cloudflare_ready` boolean
    - `git_top_score` number
    - `quality_score` number
    - `agent_score` number
    - `score` number
    - `classification` object
    - `quality_signal_confidence` QualitySignalConfidence: Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.
      - `stars_30d_delta` 'snapshot' | 'estimated'
      - `stars_30d_window_days` integer
      - `commits_30d` 'complete' | 'partial' | 'unknown'
      - `releases_180d` 'complete' | 'partial' | 'unknown'
      - `contributors_90d` 'complete' | 'partial' | 'unknown'
    - `verification` VerificationPackage: Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.
      - `schema_version` 'git-top.verification.v1', required
      - `overall_status` 'complete' | 'partial' | 'unverified', required
      - `observed_at` string, date-time, nullable, required
      - `signals` object, required
        - `activity` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `license` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `documentation` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `runtime` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `install` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `security` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `mcp` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
      - `coverage` object, required
        - `observed` integer, required
        - `inferred` integer, required
        - `not_run` integer, required
        - `unknown` integer, required
      - `next_steps` string[], required
    - `summary` ProjectSummary
      - `tl_dr` string, required: One-sentence project overview for agents.
      - `purpose` string, required: Longer agent-facing project purpose.
      - `install` string, nullable: Conservative install or setup hint when Git.Top can infer one.
      - `inputs` string[], required
      - `outputs` string[], required
      - `good_for` string[], required
      - `not_good_for` string[], required
      - `deployment` string[], required
      - `alternatives` object[], required
        - `repo` string, required
        - `reason` string, required
    - `evidence` NormalizedEvidence: Normalized evidence package for agent citation and caveat handling.
      - `classification` object
      - `quality_signal_confidence` QualitySignalConfidence: Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.
        - `stars_30d_delta` 'snapshot' | 'estimated'
        - `stars_30d_window_days` integer
        - `commits_30d` 'complete' | 'partial' | 'unknown'
        - `releases_180d` 'complete' | 'partial' | 'unknown'
        - `contributors_90d` 'complete' | 'partial' | 'unknown'
      - `verification` VerificationPackage: Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.
        - `schema_version` 'git-top.verification.v1', required
        - `overall_status` 'complete' | 'partial' | 'unverified', required
        - `observed_at` string, date-time, nullable, required
        - `signals` object, required
          - `activity` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `license` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `documentation` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `runtime` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `install` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `security` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
          - `mcp` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
            - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
            - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
            - `evidence` string[], required
        - `coverage` object, required
          - `observed` integer, required
          - `inferred` integer, required
          - `not_run` integer, required
          - `unknown` integer, required
        - `next_steps` string[], required
      - `source_fields` string[]
      - `caveats` string[]
      - `confidence_reason` string
      - `last_verified_at` string, date-time, nullable
    - `caveats` string[]
    - `confidence_reason` string
    - `source_fields` string[]
    - `last_verified_at` string, date-time, nullable
    - `similarity_score` number
    - `alternative_reason` string
    - `replacement_type` 'same_use_case' | 'same_category' | 'same_deployment' | 'ecosystem_adjacent'
    - `fit_summary` string
    - `adoption_notes` string[]
    - `replacement_risk` 'low' | 'medium' | 'high'
    - `match_signals` object
  - `next_actions` NextAction[]
    - `label` string
    - `href` string
    - `kind` string
  - `comparison_links` object
  - `evidence` NormalizedEvidence: Normalized evidence package for agent citation and caveat handling.
    - `classification` object
    - `quality_signal_confidence` QualitySignalConfidence: Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.
      - `stars_30d_delta` 'snapshot' | 'estimated'
      - `stars_30d_window_days` integer
      - `commits_30d` 'complete' | 'partial' | 'unknown'
      - `releases_180d` 'complete' | 'partial' | 'unknown'
      - `contributors_90d` 'complete' | 'partial' | 'unknown'
    - `verification` VerificationPackage: Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.
      - `schema_version` 'git-top.verification.v1', required
      - `overall_status` 'complete' | 'partial' | 'unverified', required
      - `observed_at` string, date-time, nullable, required
      - `signals` object, required
        - `activity` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `license` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `documentation` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `runtime` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `install` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `security` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
        - `mcp` VerificationSignal, required: One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.
          - `status` 'verified' | 'observed' | 'inferred' | 'not_run' | 'not_applicable' | 'unknown', required
          - `source` 'github_metadata' | 'git_top_heuristic' | 'git_top_runtime', required
          - `evidence` string[], required
      - `coverage` object, required
        - `observed` integer, required
        - `inferred` integer, required
        - `not_run` integer, required
        - `unknown` integer, required
      - `next_steps` string[], required
    - `source_fields` string[]
    - `caveats` string[]
    - `confidence_reason` string
    - `last_verified_at` string, date-time, nullable
  - `caveats` string[]
  - `confidence_reason` string
  - `source_fields` string[]
  - `last_verified_at` string, date-time, nullable
  - `metadata` Metadata, required: Common provenance envelope for agent-facing responses. Agents should require source=d1 for high-confidence production claims and disclose seed fallback.
    - `source` 'd1' | 'seed'
    - `reason` string
    - `project_count` integer
    - `generated_at` string, date-time
    - `snapshot_id` string: Stable identity for the corpus snapshot used by this response.
    - `latest_synced_at` string, date-time, nullable
    - `schema_version` 'git-top.knowledge.v1'
    - `loaded_project_limit` integer: Maximum D1 knowledge or search-candidate rows loaded into the bounded ranking set when present.
    - `truncated` boolean: Whether the D1-backed ranking or candidate set reached its limit and may omit additional matching rows.
    - `candidate_retrieval` 'd1_first': Search-only marker indicating that deterministic filters and broad query matching ran in D1 before TypeScript ranking.
    - `candidate_count` integer: Number of D1 search candidates passed to the authoritative TypeScript filter and ranking stage.
    - `candidate_limit` integer: Maximum number of D1 search candidates passed to the ranking stage.
    - `warnings` string[]: Fallback, count, freshness, or trust caveats that agents should account for before citing results.

## Other responses

- `400`: Invalid alternatives request
- `404`: Project not found

---

[API](https://skmtc.dev/git/apis/git-top-agent-api.md) · [All operations](https://skmtc.dev/git/apis/git-top-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/git/apis/git-top-agent-api/revisions/c9ebf661ef6d?raw)