Skip to content

API.md

Latest commit

 

History

History
99 lines (75 loc) · 3.14 KB

API.md

File metadata and controls

99 lines (75 loc) · 3.14 KB
Raw

Velox API

Default server: http://127.0.0.1:8787.

Runtime

  • GET /health — health check for tooling and process state.
  • GET /api/status — expanded server status mirror for runtime checks.
  • GET /api/config — renderer-safe caps, features, and environment-derived settings.
  • GET /api/settings — persisted run profile.
  • PATCH /api/settings — update run profile and broadcast settings_update.

Example settings patch:

curl -X PATCH http://127.0.0.1:8787/api/settings \
  -H 'content-type: application/json' \
  -d '{"autoSpeculation":true,"defaultDepth":"deep","defaultFreshness":"latest","maxTabs":4}'

Response shape (high-level)

  • Health/config/status include model mode, caps (MAX_AGENT_TABS, MAX_SPECULATIVE_TABS, MAX_CONCURRENT_TABS, MAX_SEARCH_QUERIES), search provider, and session count.
  • /api/settings returns all persisted profile values, including:
    • autoSpeculation
    • maxTabs
    • defaultDepth
    • defaultFreshness
    • visualAnalysis
    • theme

Prediction

  • POST /api/predict
    • Request body: { "query": "..." }
    • Response: prediction object with query, confidence, typingStage, searchPlan, budget, and wasteGuard fields.

Research lifecycle

  • POST /api/research/start

    • Request body (required): { "query": "..." }
    • Optional fields:
      • mode: speculative | committed (default committed)
      • options:
        • depth: spark | quick | standard | deep
        • maxTabs
        • visualSnapshots
        • includeVisualAnalysis
        • freshness: auto | latest | timeless
      • previousSessionId
      • supersedesSessionId
    • Response: session snapshot including id, mode, status, tabs, plan, and sources.

  • POST /api/research/demo

    • Starts a demo-mode session for no-key review paths.
    • Optional body: { "query": "...", "options": { ... } }
    • Can return 403 if DEMO_MODE_ENABLED is false in environment.

  • POST /api/research/:id/commit

    • Upgrades/copies a session to committed mode.
    • Optional body: { "query": "..." }

  • POST /api/research/:id/cancel

    • Cancels an active session and marks it cancelled.

  • DELETE /api/research/:id

    • Removes one session snapshot and in-memory state.
    • Active sessions are canceled first, then removed.

  • DELETE /api/research

    • Clears completed/cancelled/error snapshots from memory and disk.
    • Returns 409 if active sessions remain.

  • GET /api/research

    • Returns up to sessionHistoryLimit recent sessions.

  • GET /api/research/:id

    • Returns one persisted/active session snapshot.

  • GET /api/research/:id/export

    • Default: markdown, with ?format=markdown.
    • ?format=json returns portable JSON.
    • .../export.md and .../export.json are equivalent legacy paths.

WebSocket

  • GET /ws streams:
    • hello
    • prediction
    • agent_log
    • session_update
    • settings_update

The UI uses session_update as the source of truth for active tabs, source notes, synthesis state, and history.

Errors

Input validation errors return HTTP 400 with { "error": "..." }. /api/research/demo can return 403 if demo mode is disabled.