API

POST /api/v1/recommend

Body: { "query": string, "limit"?: 0-3, "mode"?: "auto" | "workflow" }

curl -X POST http://localhost:3000/api/v1/recommend \
  -H "Content-Type: application/json" \
  -d '{"query": "build a landing page today"}'

Response includes the recommended tools plus task understanding, first steps, route cards, workflow chains, and a copy-ready prompt when available.

{
  "task": { "intent": "design", "output": "poster", "userLevel": "beginner" },
  "primary": { "toolId": "canva", "confidence": "high", "reason": "..." },
  "actionGuide": {
    "firstSteps": ["Open the tool", "Paste the prompt"],
    "copyPrompt": "Create a poster for..."
  },
  "routeCards": [
    {
      "label": "Fastest route",
      "toolIds": ["canva"],
      "tradeoff": "Fast, but less custom."
    }
  ]
}

Optional header: Authorization: Bearer YOUR_OPENAI_KEY (BYOK)

Streaming: add ?stream=1 and accept text/event-stream. The stream emits progress events before the final result.

GET /api/v1/config

Public client config for BYOK prompts and deployment mode.

GET /api/v1/credits

Returns whether this deployment is metered and the current credit balance when applicable.

POST /api/v1/checkout

Creates a Stripe Checkout Session for credit top-ups when Stripe is configured.

GET /api/v1/tools

Query: ?category=search&page=1&pageSize=50

GET /api/v1/tools/:id

Single tool from the catalog.

POST /api/v1/feedback

Body: { "query": string, "rating": "good_match" | "not_right" | "too_advanced" }

Stores lightweight recommendation feedback for product tuning.

GET /api/v1/health

Status and catalog version.