---
title: "Search project knowledge by query, category, deployment, difficulty, language, project type, confidence, and Cloudflare readiness; large corpora disclose bounded D1-first candidate retrieval in metadata."
method: GET
path: "/api/search"
---

# Search project knowledge by query, category, deployment, difficulty, language, project type, confidence, and Cloudflare readiness; large corpora disclose bounded D1-first candidate retrieval in metadata.

`GET /api/search`

## Request

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

## Query parameters

- `q` string
- `category` string
- `deployment` string
- `difficulty` string
- `language` string
- `project_kind` string
- `min_confidence` string
- `cloudflare_ready` string
- `ranking` string
- `profile` string
- `limit` string
- `cursor` string
- `require_d1` string

## Response `200`

Project search results with metadata

- SearchResponse
  - `profile` 'full' | 'compact' | 'decision' | 'evidence', required
  - `query` object, required
  - `search` object, required
    - `applied_filters` object
    - `known_filter_values` object
    - `empty_reason` string
    - `suggestions` string[]
    - `query_interpretation` object
      - `original` string
      - `normalized` string
      - `transformations` string[]
  - `projects` object[], required: Project cards shaped by profile. compact returns bounded identity, fit, score, and verification fields; full preserves the complete project card.
  - `knowledge` object[]: Raw project knowledge rows retained only for the default full profile.
  - `page` CursorPage, required
    - `offset` integer, required
    - `limit` integer, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required: Opaque cursor for the next page, or null on the final page.
    - `snapshot_id` string, required: Corpus snapshot to which this page and cursor are bound.
  - `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.

---

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