SPB Git

Repository Public

API_INVENTORY.md 11.1 KB 159 lines markdown

1<!-- Author: Simon-Pierre Boucher — contact@spboucher.ai · File: docs/API_INVENTORY.md -->2# API inventory34Part 1 (1.x routes) was read in the backend source (`server/**`, v5.8.0) and, where marked ✔, called by the integration5suite — re-run for 2.0.0 against the frozen VQuant Next test backend (M2U64:5058). Part 2 lists what 2.0.0 adds6(backend 6, contract `vquant-next/docs/next/CONTRACT.md`), called through the shared package VQuantKit. The client calls no route that is not in this table7(`Core/Services/VQuantAPI.swift`, `Core/Auth/AuthService.swift`).89Transport: HTTPS, JSON. Native clients send `X-VQ-Client: vquant-macos/<version>` (2.0.0: the server then returns the 19 lab engines and the `cancelled` job status) and `Authorization: Bearer vqn_…`.10There is **no WebSocket** endpoint. Streams are server-sent events.1112## Authentication — `server/access.ts`, `server/native.ts`1314| Route | Purpose | Client | Verified |15|---|---|---|---|16| `GET /api/health` | liveness, uptime (open) | `health()` | ✔ |17| `GET /.well-known/apple-app-site-association` | `webcredentials` for the Apple app id (open) — **added v5.8.0** | system | ✔ (Apple CDN) |18| `POST /api/native/login/options`, `/verify` | passkey sign-in → device token — **added** | `AuthService.signIn` | ✔ |19| `POST /api/native/register/options`, `/verify` | enrol from a setup-link token → passkey + device token — **added** | `enrol(setupLink:)` | ✔ |20| `GET /api/native/session` | who, which device — **added** | `session()` | ✔ |21| `POST /api/native/logout` | revoke this device — **added** | `signOut()` | ✔ |22| `POST /api/native/reauth/options`, `/verify` | fresh check, 5 min — **added** | `reauthenticate()` | ✔ |23| `GET /api/native/devices` | device sessions and passkeys — **added** | `devices()` | ✔ |24| `DELETE /api/native/devices/:id` | revoke another device (fresh check) — **added** | `revokeDevice` | ✔ |25| `DELETE /api/native/passkeys/:ref` | delete a passkey, never the last (fresh check) — **added** | `deletePasskey` | route read, not exercised |26| `POST /api/passkey/*`, `/setup/:token`, `/lock`, `GET /api/me` | web gate (cookie `vq_access`) | not used: browser only | — |2728## Market data — `server/routes/fmp.ts` (proxy to Financial Modeling Prep)2930| Route | Client | Verified |31|---|---|---|32| `GET /api/fmp/indices` (12 indices, 45 s server cache) | `indices()` | ✔ |33| `GET /api/fmp/gainers`, `/losers`, `/actives` | `movers()` | ✔ |34| `GET /api/fmp/market-hours` | `marketHours()` | ✔ |35| `GET /api/fmp/search?q=&limit=` — **added v5.8.0** | `search()` | ✔ |36| `GET /api/fmp/quote/:symbol` | `quote()` | ✔ |37| `GET /api/fmp/company-profile/:symbol` | `profile()` | ✔ |38| `GET /api/fmp/chart/full/:symbol?from&to` | `dailyBars()` | ✔ |39| `GET /api/fmp/chart/intraday/:symbol?interval&from&to` (1min…4hour) | `intradayBars()` | ✔ |40| `GET /api/fmp/{income-statement,balance-sheet,cash-flow,key-metrics,financial-ratios}/:symbol?period&limit` | `dataset()` | ✔ |41| `GET /api/fmp/{analyst-estimates,price-target,upgrades-downgrades,earnings-surprises,dividend-history,institutional-holders,esg-score}/:symbol` | `dataset()` | ✔ |42| `GET /api/fmp/{financial-news,insider-trading}/:symbol?limit` | `dataset()` | ✔ |43| `GET /api/fmp/historical-price/:symbol` | `dataset(.dailyPrices)` | ✔ |44| `GET /api/fmp/stock-quote/:symbol`, `/intraday/:symbol`, `/chart/light/:symbol`, `/price-target-summary/:symbol` | not used (duplicates of the above) | — |4546The proxy offers a page size (`limit`) on some datasets and no offset: "server-side pagination" in the Data Explorer47is the choice of that page size.4849## Research agent — `server/routes.ts`, `routes/generations.ts`, `routes/reports.ts`5051| Route | Purpose | Client | Verified |52|---|---|---|---|53| `POST /api/chat` | starts an analysis job; the response is its event stream | `startAnalysis` | ✔ real run |54| `GET /api/generations` | jobs of the last 24 h | `generations()` | ✔ |55| `GET /api/generations/:id/stream?from=n` | replay from event n, then live | `watchGeneration` | ✔ replay and mid-stream join |56| `POST /api/generations/:id/cancel` | Stop | `cancelGeneration` | ✔ |57| `GET /api/sessions[?q=]`, `GET/PATCH/DELETE /api/sessions/:id` | conversations | `sessions`, `conversation`, `renameSession`, `pinSession`, `deleteSession` | ✔ |58| `POST /api/generate-pdf`, `/generate-docx`, `/convert-to-slides` | server-rendered exports | `renderPDF`, `renderDOCX`, `renderSlides` | PDF ✔; DOCX, slides not exercised |59| `GET /api/shared-reports`, `GET /api/share/:id`, `POST /api/share` | shared reports | `sharedReports`, `sharedReport`, `share` | list ✔; publish not exercised |60| `GET /figures/*`, `/plots/*`, `GET /api/download/:file` | figures and generated files | `asset(path:)` | figures route read; fetch path-confined (tested) |61| `POST /api/speech-to-text` | dictation (needs `ELEVENLABS_API_KEY`, absent from the server's environment) | not used | — |6263Event types of a stream (all decoded by `GenerationEvent`): `job`, `status`, `text`, `thinking`, `tools`,64`tool_start`, `tool_complete`, `tool_result`, `tool_error`, `python_code`, `custom_python_figures`, `plan`,65`agent_start`, `agent_tool`, `agent_done`, `workspace`, `sources`, `followups`, `error`, `done`. An unknown type is66counted and reported in the interface, never dropped silently.6768Server limits the client reports as they are: 4 running analyses per person, one per conversation; jobs live in the69server's memory (a restart ends them); replay for 20 minutes after the end.7071## Workspace — `server/routes/workspace.ts`7273`GET /api/workspace`; `POST/DELETE /api/workspace/memories[/:id]`; `PUT/DELETE /api/workspace/portfolio/:symbol`;74`POST/PATCH/DELETE /api/workspace/watches[/:id]`; `POST /api/workspace/watches/:id/run`. All used, all ✔ except75`watches/:id/run` (would start a real analysis on the schedule's model).7677## Quant Engine — `server/routes/quant.ts` (**added v5.8.0**)7879`GET /api/quant/tools`; `POST /api/quant/jobs`; `GET /api/quant/jobs`; `GET/DELETE /api/quant/jobs/:id`. ✔ including80a job that fails. Engines: `garch`, `var`, `monte_carlo`, `options`, `portfolio_optimization`, `risk_metrics` — the81executors the agent already used, with the agent's defaults. No cancel route: the executors cannot be interrupted.8283## Usage — `server/routes/analytics.ts`, `routes/admin.ts`8485`GET /api/analytics/real-time-stats` is used by network diagnostics (✔). `GET /api/admin/database` and the delete86routes under `/api/admin/*` are **not** exposed: they act on every person's data with no per-person check, which a87client distributed to several people should not offer.8889# Part 2 — backend 6 routes used by 2.0.09091Evidence: **T** called by an integration test of this repository against 5058 · **L** called by the running app92against 5058 and its result seen in a capture · **K** covered by the kit's own fixture/live tests only · **—** written,93not exercised. Client column: `vq` = `app.vq` (VQuantKit).9495## Sync — CONTRACT §19697| Route | Client | Evidence |98|---|---|---|99| `GET /api/v2/sync/stream` (SSE: hello, change, hint) | `VQSyncEngine.start` | L (toolbar indicator "Synced"; a chart edited by a raw PUT appeared in the open app) |100| `GET /api/v2/sync/changes?since=` | `VQSyncEngine.pull` | L, K |101| `GET/PUT/DELETE /api/v2/objects/:kind/:id` | `VQSyncEngine.flush`, `vq.objects` | T (notes, projects, charts through raw GET/PUT round trips), L |102| `GET /api/v2/objects/:kind/:id/versions[/:rev]` | Studio note versions | T |103104## Models, usage, trace — §2105106| Route | Client | Evidence |107|---|---|---|108| `GET /api/v2/models` | composer model picker, Settings › Models | T, L |109| `GET /api/v2/models/route` | Settings routing preview | T, L |110| `POST /api/chat` with `mode: research`, `model: auto`, `budget`, `projectId` | Research composer | L (one fast `auto` run, one research study); `projectId` — |111| stream events `model_routed`, `budget`, `quant_job`, `provenance`, `done.usage` | run view, usage line | L (`model_routed`, usage, provenance); `budget`, `quant_job` not observed live |112| `GET /api/v2/generations/:id/trace` | trace sheet | L |113| `GET /api/v2/usage?days=` | Settings › Usage & Cost | L |114115## Data layer and terminal — §3116117| Route | Client | Evidence |118|---|---|---|119| `GET /api/v2/market/overview` | Overview, menu-bar extra | L |120| `GET /api/v2/data/quotes?symbols=` (≤ 60 per call, batched) | Watchlists, Portfolios, Overview | T (70 refused, 60 + 10 accepted), L |121| `GET /api/v2/data/bars/:symbol` | Charting | T (`^GSPC` daily and 15 m), L |122| `GET /api/v2/data/statements/:symbol` | Statements | L |123| `GET /api/v2/search` | command palette | L |124| `GET /api/v2/data/health` | Settings › Data Providers | L |125126## Quant Lab — §4127128| Route | Client | Evidence |129|---|---|---|130| `GET /api/quant/tools` (19 tools with a 2.x header) | catalogue | T, L |131| `POST /api/quant/jobs` (`projectId` optional), `GET /api/quant/jobs[/:id]`, `DELETE` | jobs | T, L; `projectId` — |132| `POST /api/quant/jobs/:id/cancel` | cancel | T (lab job cancelled; legacy → `not_cancellable`) |133134## Research Studio, review, memory, audit — §5–§7135136| Route | Client | Evidence |137|---|---|---|138| `GET /api/v2/projects/:id/bundle` | project page | T, L |139| `POST /api/v2/projects/:id/export` + `GET /api/download/:file` | export sheet | T (md, md with `include`, zip, tex, pdf) ; saving through the panel — |140| `POST /api/v2/projects/:id/run` | not used: the project composer hands the question to Research (`/api/chat` with `projectId`) | — |141| `POST /api/v2/reviews` | "Request review" | — (calls a model; never started from this client). Rendering of an existing `review` object: L |142| `GET /api/v2/memory`, `PUT …/settings`, `DELETE …?scope=`, `GET …/export`, `PATCH /api/workspace/memories/:id` | Settings › Memory, project memory | T (project-scoped add, patch, delete), L (listing); settings, bulk delete, export — |143| `GET /api/v2/audit` | Settings › Audit Log | L |144145## Autonomous research — §9146147| Route | Client | Evidence |148|---|---|---|149| `GET /api/v2/research/sandbox` | mode availability, Environnement, Settings › Research | T, L |150| `GET/POST /api/v2/research/sessions`, `GET …/:id` | Studies list, cockpit rebuilt from REST | T, L |151| `POST …/:id/upload` (multipart), `GET …/:id/inspect` | dataset attachment | T (201, 415 with the server's sentence), L |152| `GET …/:id/files`, `…/file` | Files, Code | T, L |153| `GET …/:id/experiments`, `…/runs`, `GET /api/v2/research/runs/:id`, `POST …/cancel` | Experiments, Environment | L (experiments); runs, logs, cancel — (no background run occurred) |154| `GET /api/v2/research/approvals`, `POST …/:id` | approvals | T (pending list); answering — (no approval occurred in the live study; the kit's card is tested on sequences recorded from the server) |155| stream events `research_workspace`, `dataset`, `research_file`, `code_execution`, `experiment`, `figure_lint`, `quality_gate` | cockpit | L; `package_install`, `research_run`, `approval_*`, `budget`, `plan` not observed live |156157Routes of backend 6 the client does not call: `POST /api/v2/projects/:id/run` (see above), the web-only cookie routes,158`/api/admin/*` (unchanged reason: no per-person check).159
Files main
Menu

Theme