---
title: "Run Graph Reasoning Protocol over the knowledge graph."
method: POST
path: "/api/grp/query"
---

# Run Graph Reasoning Protocol over the knowledge graph.

`POST /api/grp/query`

## Request

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

## Query parameters

- `require_d1` string

## Request body

- GrpRequest: Graph Reasoning Protocol request for project planning, comparison, discovery, or stack composition.
  - `goal` string, required: Natural-language project selection, comparison, planning, or stack-composition goal.
  - `mode` 'plan' | 'compare' | 'find' | 'compose': Reasoning mode. Defaults to plan when omitted.
  - `constraints` object
    - `deploy` string[]
    - `license` string
    - `complexity` 'low' | 'medium' | 'high'
    - `agent_ready` boolean
    - `language` string
    - `category` string
  - `context` object
    - `previous_selected_projects` string[]
    - `current_stack` string[]

## Response `200`

Graph-grounded project set, plan, comparison, or stack

- GrpResponse: Graph Reasoning Protocol result for planning, composing, comparing, or finding project sets.
  - `solution_paths` object[]
  - `recommended_stack` object[]
  - `nodes` object[]
  - `edges` object[]
  - `explanation` string[]
  - `decomposition` object
  - `confidence` string
  - `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` object

---

[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)