The runtime interface, not a placeholder.

What this API is.

Scout currently exposes an application runtime API for ProjectHub Recruiter Alpha. The route surface is real and usable by the ProjectHub frontend and engineering tooling, but it is not documented here as a stable public developer platform.

Runtime environments.

The release specification separates production and development staging. These are application endpoints, not customer-specific base URLs or a versioned public API gateway.

JSON, CORS, limits.

Routes present in the September 15 released source.

This table deliberately omits routes that only survive in older documentation. In particular, /api/think and /api/stats are not listed as current server routes because they are not present in the current server source reviewed for this page.

POST /api/chat

The chat route owns the end-to-end request deadline, conversation-state lookup, policy classification, optional query rewrite, local retrieval, agent execution, validation, response shaping, telemetry, and memory update.

Request body

curl -sS https://projecthub-chat.bradleymatera.dev/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Which project best demonstrates debugging?",
    "sessionId": "example-tab-1",
    "history": [
      {
        "user": "What is Bradley strongest at?",
        "assistant": "..."
      }
    ]
  }'

Execution sequence

Success payload.

The exact metadata varies by path, but current chat responses expose more than visible prose. Clients should treat fields other than reply as runtime metadata, not a frozen public schema.

{
  "ok": true,
  "reply": "...",
  "provider": "cloudflare",
  "model": "@cf/meta/llama-3.1-8b-instruct-fast",
  "fallback": false,
  "grounded": false,
  "proseSource": "MODEL_GENERATION",
  "pipeline": ["knowledge-loaded", "policy:...", "cache-miss", "scout-agent-lite:...", "shaped"],
  "contract": {
    "intent": "...",
    "directAnswer": "...",
    "factState": "TRUE | FALSE | UNKNOWN",
    "evidenceStrength": "...",
    "claimCeiling": "..."
  },
  "sessionMemory": {
    "turns": 5,
    "retained": true
  },
  "agent": {
    "agentMode": "lite",
    "inferenceProvider": "cloudflare",
    "generationCalls": [],
    "retrievalCandidates": [],
    "selectedEvidence": []
  }
}

Prose source

Check ok, not just HTTP status.

Current runtime behavior mixes HTTP status codes and JSON-level error states. Some operational failures return a JSON body with ok:false using the default HTTP 200 status.

const response = await fetch(base + '/api/chat', options);
const payload = await response.json();

if (!response.ok || payload.ok === false) {
  throw new Error(payload.error || `HTTP ${response.status}`);
}

console.log(payload.reply);

Three different health surfaces.

curl -fsS https://projecthub-chat.bradleymatera.dev/health/ready

GET /api/retrieve

The server labels this route as a dev-only retrieval testing endpoint. It exposes query understanding plus current BM25 behavior without running normal chat generation.

curl -sS 'http://127.0.0.1:3000/api/retrieve?q=what%20did%20he%20build'

The response exposes rewritten, normalized, intent, retrievalMethod, BM25 results, and the legacy substring fallback results for comparison.

Model probes are engineering surfaces.

GET /api/diagnose

This endpoint still probes the local Ollama URL, attempts a bounded generation when reachable, validates the result, and returns a short preview. That makes it useful for the local-development path, but it should not be read as the authoritative production-provider health check.

GET /api/agent-probe

This endpoint runs the agent probe through the current model router, reports engine/agent mode, reachability, structured-output capability, latency, available/pinned local models, and the session-state store size.

GET /api/knowledge-health

This diagnostic walks the loaded knowledge object, reports populated/empty field coverage, aggregates topic/gap telemetry, and includes legacy learned-answer structures that remain for compatibility.

Browser-local packet/validate flow.

Current develop contains an experimental server-assisted browser-local path. The server still owns retrieval/evidence preparation and final validation; the browser can supply the generation step.

Operational telemetry.

/health and /api/chat-log expose internal runtime/usage information. These are operational surfaces, not a public analytics API contract.

GET /api/costs

The route is always mounted, but its behavior depends on COST_TRACKER.

Current application controls.

Scout also has application-level response-policy, safety, grounding, relationship, provenance and false-claim controls, but those are answer-quality/security layers rather than HTTP authentication.

No frozen public schema yet.

The current interface evolves with ProjectHub. A future commercial Scout API should introduce explicit versioning, authentication, tenant isolation, compatibility policy, customer-safe telemetry, and a documented deprecation process before third parties are told to depend on these internal shapes.

Copyable requests.

Clear one session

curl -sS http://127.0.0.1:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"action":"clear","sessionId":"example-tab-1"}'

Detailed runtime health

curl -sS http://127.0.0.1:3000/health

Contextual retrieval diagnostic

HISTORY='[{"user":"Tell me about ProjectHub","assistant":"..."}]'
curl -sS --get http://127.0.0.1:3000/api/retrieve \
  --data-urlencode 'q=what technology does it use?' \
  --data-urlencode "h=$HISTORY"

Prepare a browser-local packet

curl -sS http://127.0.0.1:3000/api/client-packet \
  -H 'Content-Type: application/json' \
  -d '{"message":"Does he know AWS?","sessionId":"local-demo"}'

Where each contract comes from.