Fleet Vector API — Documentation

⚡ Quick Start

All endpoints accept and return JSON. No API key needed for read operations — just curl and go. The embedding model is @cf/baai/bge-small-en-v1.5 producing 384-dimensional vectors stored in Cloudflare Vectorize.

Embedding model: @cf/baai/bge-small-en-v1.5 — a compact English-language model optimized for semantic similarity. All 384 dimensions are L2-normalized before indexing. Text is truncated to 2,000 characters per embedding call.

Semantic Search POST

curl -X POST $BASE/search \
  -H "Content-Type: application/json" \
  -d '{"query":"http client","topK":5}'

Index Stats GET

curl $BASE/stats

Find Similar POST

curl -X POST $BASE/similar \
  -H "Content-Type: application/json" \
  -d '{"crate_name":"reqwest"}'

Recommend POST

curl -X POST $BASE/recommend \
  -H "Content-Type: application/json" \
  -d '{"context":"async websocket","topK":3}'

Authentication: Only POST /ingest requires a Bearer token. All other endpoints are public.

🔍 Search & Discovery

POST /search 🔓 Public

Perform a semantic search across all indexed crates. Your query is embedded using the same model as the crate data, then matched against the Vectorize index using cosine similarity. Results are enriched with full metadata from KV storage.

Request Body

Field	Type	Required	Description
query	string	required	Natural language search query
topK	number	optional	Max results to return (1–50, default 10)

Example Request

curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "async http client with middleware",
    "topK": 3
  }'

Example Response — 200

{
  "query": "async http client with middleware",
  "model": "@cf/baai/bge-small-en-v1.5",
  "results": [
    {
      "id": "reqwest",
      "score": 0.892,
      "name": "reqwest",
      "description": "An HTTP client with middleware support",
      "version": "0.12.4",
      "domain": "networking",
      "tests": 142,
      "loc": 8200,
      "keywords": ["http", "async", "client"]
    }
  ],
  "count": 1
}

Error Responses

Status	Condition	Body
400	Missing `query`	`{"error": "Query required"}`
500	Internal error	`{"error": "<message>"}`

POST /similar 🔓 Public

Find crates semantically similar to a known crate. Looks up the crate's metadata, embeds its description + keywords, and queries Vectorize for nearest neighbors. The source crate is excluded from results.

Request Body

Field	Type	Required	Description
crate_name	string	required*	Crate name to find similars for
name	string	alias	Alias for `crate_name`
id	string	alias	Alias for `crate_name`
topK	number	optional	Max results (default 10)

* One of crate_name, name, or id is required.

Example Request

curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/similar \
  -H "Content-Type: application/json" \
  -d '{ "crate_name": "reqwest", "topK": 3 }'

Example Response — 200

{
  "crate": "reqwest",
  "similar": [
    {
      "id": "hyper",
      "score": 0.914,
      "metadata": { "name": "hyper", "desc": "..." }
    }
  ],
  "count": 1
}

Error Responses

Status	Condition	Body
400	No identifier provided	`{"error": "crate_name, name, or id required"}`
404	Crate not in index	`{"error": "Crate not found: <name>. Try /search…"}`

POST /recommend 🔓 Public

Get context-aware crate recommendations with quality-weighted scoring. Over-fetches from Vectorize (3× topK), then applies quality bonuses for test count, lines of code, and description quality. Each recommendation includes a human-readable reasoning array explaining why it was selected.

Request Body

Field	Type	Required	Description
context	string	required	What you're trying to build — be descriptive
topK	number	optional	Max recommendations (default 5)

Example Request

curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "context": "building a real-time websocket server with tokio",
    "topK": 3
  }'

Example Response — 200

{
  "context": "building a real-time websocket server with tokio",
  "recommendations": [
    {
      "name": "tokio-tungstenite",
      "description": "Async WebSocket streams",
      "domain": "networking",
      "version": "0.21.0",
      "semantic_score": 0.887,
      "composite_score": 0.962,
      "quality_signals": {
        "tests": 34,
        "loc": 2100,
        "has_description": true
      },
      "reasoning": [
        "Semantic relevance: 88.7%",
        "34 tests",
        "2100 LOC",
        "Domain: networking"
      ]
    }
  ],
  "count": 1
}

Error Responses

Status	Condition	Body
400	Missing `context`	`{"error": "context required"}`

📊 Analysis

POST /gap-analysis 🔓 Public

Identify underdeveloped crates with quality gaps. Scans for missing descriptions, zero/low test counts, and stub-level code. Returns prioritized suggestions with actionable fixes and high-quality reference crates from other domains.

Request Body

Field	Type	Required	Description
domain	string	optional	Restrict analysis to a specific domain. Omit to scan all crates.

Example Request

curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/gap-analysis \
  -H "Content-Type: application/json" \
  -d '{ "domain": "networking" }'

Example Response — 200

{
  "domain": "networking",
  "total_crates": 87,
  "quality_crates": 62,
  "gap_crates": 25,
  "gap_percentage": 29,
  "suggestions": [
    {
      "name": "some-crate",
      "domain": "networking",
      "issues": ["no_tests", "missing_description"],
      "severity": 2,
      "priority": "high",
      "suggestion": [
        "Add comprehensive test suite",
        "Write a descriptive README and description"
      ]
    }
  ],
  "references": [
    { "name": "well-tested-crate", "reason": "high_quality_reference" }
  ]
}

Error Responses

Status	Condition	Body
404	No crates found	`{"error": "No crates in domain: <name>"}`

Issue Types

Issue	Trigger
missing_description	Empty or <10 chars
no_tests	Test count is 0
low_test_count	Between 1–4 tests
zero_loc	0 lines of code
low_loc	Between 1–99 LOC

📦 Ingestion

POST /ingest 🔒 Bearer Token

Embed and index crates into Vectorize + KV. Accepts a single crate, an array of crates, or an object with a crates array. Each crate's name, description, keywords, and README excerpt are concatenated and embedded. Metadata is stored in both Vectorize (truncated) and KV (full). Maximum 50 crates per request.

Authentication required. Include Authorization: Bearer <INGEST_SECRET> header. Requests without a valid token receive a 401 response.

Request Body

Field	Type	Required	Description
crates	CrateInput[]	required	Array of crate objects (or single object, or raw array)

CrateInput Schema

Field	Type	Required	Description
name	string	required	Crate name (used as Vectorize ID)
description	string	required	Short description
readme	string	required	README content (first 1,500 chars used)
version	string	optional	Semver string (default "0.1.0")
domain	string	optional	Category domain (default "unknown")
wave	number	optional	Deployment wave number
tests	number	optional	Test count
loc	number	optional	Lines of code
github_url	string	optional	GitHub repository URL
keywords	string[]	optional	Keyword tags

Example Request

curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
  -d '{
    "crates": [
      {
        "name": "my-crate",
        "description": "A fantastic crate",
        "readme": "# My Crate\n\nDoes awesome things...",
        "version": "1.0.0",
        "domain": "utilities",
        "tests": 42,
        "loc": 3200,
        "keywords": ["utility", "helper"]
      }
    ]
  }'

Example Response — 200

{
  "ok": true,
  "inserted": 1,
  "vectorize_upsert": {
    "ids": ["my-crate"],
    "count": 1
  }
}

Error Responses

Status	Condition	Body
401	Missing or invalid token	`{"error": "Unauthorized"}`
400	Empty crates array	`{"error": "No crates"}`
400	Over 50 crates	`{"error": "Max 50 per request"}`

📖 Read Endpoints

GET /stats 🔓 Public

Returns index statistics — total crate count, last ingest timestamp, embedding model info, and backend details. Lightweight endpoint for health checks.

Example Request

curl https://fleet-vector-api.casey-digennaro.workers.dev/stats

Example Response — 200

{
  "service": "fleet-vector-api",
  "model": "@cf/baai/bge-small-en-v1.5",
  "dimensions": 384,
  "crate_count": 1012,
  "last_ingest": "2026-06-12T10:30:00.000Z",
  "backend": "cloudflare-vectorize",
  "index": "fleet-crates"
}

GET /clusters 🔓 Public

Returns all crates grouped by domain clusters with aggregate stats (total tests, LOC, top keywords). Also computes inter-cluster similarity based on shared keywords between domains.

Example Request

curl https://fleet-vector-api.casey-digennaro.workers.dev/clusters

Example Response — 200

{
  "clusters": [
    {
      "domain": "networking",
      "crate_count": 87,
      "crates": ["reqwest", "hyper", "…"],
      "total_tests": 3420,
      "total_loc": 210000,
      "avg_tests_per_crate": 39,
      "top_keywords": ["http", "async", "tcp"]
    }
  ],
  "inter_cluster": [
    {
      "domains": ["networking", "web"],
      "shared_keywords": ["http", "async"],
      "similarity": 0.42
    }
  ],
  "total_domains": 12,
  "total_crates": 1012
}

GET /dashboard 🔓 Public

Dashboard summary for website rendering. Includes quality breakdown (high/medium/low/stub), domain distribution, recently published crates, most similar crate pairs, and per-domain gap analysis summary.

Example Request

curl https://fleet-vector-api.casey-digennaro.workers.dev/dashboard

Example Response — 200

{
  "total_crates": 1012,
  "quality_breakdown": {
    "high": 340,
    "medium": 412,
    "low": 198,
    "stub": 62
  },
  "domain_distribution": {
    "networking": 87,
    "web": 134
  },
  "recently_published": [
    { "name": "new-crate", "domain": "utilities", "version": "0.1.0" }
  ],
  "most_similar_pairs": [
    { "crate_a": "hyper", "crate_b": "reqwest", "score": 0.94 }
  ],
  "gap_analysis": {
    "networking": { "total": 87, "gaps": 25 }
  },
  "generated_at": "2026-06-12T13:00:00.000Z"
}

GET /crates/:name 🔓 Public

Retrieve full metadata for a single crate by name. Returns the complete CrateMetadata object stored in KV, including embedding timestamp and model info.

Path Parameters

Parameter	Type	Description
name	string	Exact crate name (case-sensitive)

Example Request

curl https://fleet-vector-api.casey-digennaro.workers.dev/crates/reqwest

Example Response — 200

{
  "name": "reqwest",
  "description": "An HTTP client with middleware support",
  "version": "0.12.4",
  "domain": "networking",
  "wave": 3,
  "tests": 142,
  "loc": 8200,
  "github_url": "https://github.com/seanmonstar/reqwest",
  "keywords": ["http", "async", "client"],
  "embedded_at": 1718197200000,
  "model": "@cf/baai/bge-small-en-v1.5",
  "dims": 384
}

Error Responses

Status	Condition	Body
404	Crate not in index	`{"error": "Not found: <name>"}`

ℹ️ General

CORS: All endpoints include Access-Control-Allow-Origin: * headers. OPTIONS preflight requests are handled automatically.

Cache: All responses include Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate. Every request hits live data.

GET /health 🔓 Public

Lightweight health check endpoint. Returns service status, model, and dimensions.

Example

curl https://fleet-vector-api.casey-digennaro.workers.dev/health

Response — 200

{
  "status": "ok",
  "service": "fleet-vector-api",
  "model": "@cf/baai/bge-small-en-v1.5",
  "dims": 384,
  "backend": "vectorize",
  "timestamp": 1718197200000
}

Rate limits: This API runs on Cloudflare Workers. Standard Workers limits apply. Embedding queries are relatively expensive — avoid polling in tight loops.