Skip to content

1.1 rest

Jump to bottom
wiki[bot] edited this page Aug 23, 2026 · 4 revisions

1.1. REST API

All endpoints are versioned under /api/v1 and documented live by Swagger at /api-docs. The server speaks JSON; the harness intake endpoint additionally accepts multipart/form-data for image uploads.

Harness (@Controller('harness'))

The conversation engine's surface. Source: server/src/modules/harness/controllers/harness.controller.ts with OpenAPI decorators in decorators/harness.openapi.ts.

Method Path Purpose Success
POST /harness Submit a prompt (text + images) for streaming processing 202
POST /harness/cancel Signal cancellation of an in-flight job 202
POST /harness/warm Fire-and-forget model warm-up (pre-load weights in Ollama) 200
GET /harness/models List available Ollama models (local or cloud) 200

POST /api/v1/harness

The one entry point for all interaction. Accepts multipart/form-data:

  • Header x-harness-llm — model name (required, 400 otherwise).
  • Field prompt — the message array (roles + content), JSON string.
  • Files images — zero or more image parts.
  • Query — requestId, sessionId, conversationId, roomId (identity/correlation), stream, numCtx (context window override), event (the socket event name the dashboard listens on), think, hasNewImages, sessionMetadata (client-supplied session metadata, e.g. image hashes for dedup), language (ISO-639-1 code of the active UI locale — browser-detected or user-selected).

Response (synchronous):

{ "realtime": { "event": "<event>", "roomId": "<room>", "requestId": "<id>" } }

Images are hashed/deduplicated against sessionMetadata.images[*].hash before becoming job payloads; previously uploaded payloads are re-used from MinIO (see 1.5). The actual assistant output arrives asynchronously on the Socket.IO room — see 1.4.

POST /api/v1/harness/cancel

Body: CancelHarnessJobDto ({ requestId, roomId, event, stream }). Cancels the running job for requestId; the UI receives cancel_result on the socket (see 1.4).

GET /api/v1/harness/models

Proxies the Ollama model catalogue via OllamaModelsService so the dashboard's model selector reflects whatever the configured OLLAMA_HOST actually serves — local pull list or Ollama Cloud roster — including each model's default numCtx where known. Supports conditional requests: the response carries an ETag (built from the catalogue + numCtx options) and returns 304 Not Modified when the client's If-None-Match matches.

POST /api/v1/harness/warm

Body: WarmModelDto ({ model }). Fire-and-forget model warm-up: pre-loads a model's weights in Ollama so the first prompt does not stall on a cold load. Failures are logged server-side and never surfaced to the caller (best-effort).

Playlists (@Controller('playlists'))

Server-side persisted video playlists, scoped by session and conversation (HarnessPlaylist — see 1.5). Playlist names are user input, so every path segment is URL-encoded.

Method Path Purpose
GET /playlists/:sessionId List all playlists for a session
GET /playlists/:sessionId/:conversationId List playlists of a conversation
GET /playlists/:sessionId/:conversationId/:name Fetch one playlist
PUT /playlists/:sessionId/:conversationId/:name Upsert a playlist (create/replace)
PUT /playlists/:sessionId/:conversationId/:name/rename Rename a playlist
DELETE /playlists/:sessionId/:conversationId/:name Delete a playlist

These back the dashboard's playlist panel, transport bar, and floating playlist (see 2.2).

Queue observability (@Controller('bullmq'))

Method Path Purpose
GET /bullmq/live Live queue status (counts per state) — feeds the SysCtl queue console
GET /bullmq/retry-config Effective retry/backoff configuration

Dead-letter queue (@Controller('dlq'))

Method Path Purpose
GET /dlq List envelopes with filters (status, queue, requestId, search, limit/offset)
GET /dlq/:requestId Fetch one DLQ envelope
POST /dlq Create a DLQ record manually
PATCH /dlq/:requestId Edit a DLQ record (e.g. fix payload before replay)
PATCH /dlq/:requestId/upsert Upsert a record
DELETE /dlq/:requestId Drop a record
POST /dlq/reinstate Re-queue selected records into BullMQ
DELETE /dlq Cleanup: purge eligible Removed records (retention/amount policy)

These back the dashboard's DLQ area (list, edit, reinstate; counts polled every 30 s).

Storage (@Controller('storage'))

MinIO object API scoped by session and conversation:

Method Path Purpose
GET /storage/info Bucket/usage info
GET /storage/:sessionId/:conversationId List payloads of a conversation
GET /storage/:sessionId/:conversationId/:hash Fetch one image payload
GET /storage/:sessionId/:conversationId/:hash/exists Existence probe (dedup before upload)
DELETE /storage/:sessionId/:conversationId/:hash Remove one payload
DELETE /storage/:sessionId/:conversationId Remove all payloads of a conversation

Provider overrides (@Controller('provider-overrides'))

Method Path Purpose
GET /provider-overrides Merged config for all providers (API keys masked) — feeds SysCtl
PUT /provider-overrides Partial update of provider configs (encrypted at rest; masked keys kept)
DELETE /provider-overrides/:provider Reset/clear overrides for a provider (sysctl)

Provider keys are serper, brightData, youtube, sources, eodhd, layouts; legacy webpageFetch rows are migrated to scrape on boot.

Ollama overrides (@Controller('ollama-overrides'))

Method Path Purpose
GET /ollama-overrides Current Ollama connection config (host + OLLAMA_API_KEY)
PUT /ollama-overrides Update the Ollama connection (host / API key)
DELETE /ollama-overrides Reset the Ollama connection to defaults

Memory overrides (@Controller('memory-overrides'))

Memory system variables (sysctl → system): global settings layered over env defaults, persisted in the shared provider_overrides row memory, restored on boot. Currently cognitionLimit — the cognition profile character cap (env baseline MEMORY_COGNITION_LIMIT, default 5000, clamped 500–32000).

Method Path Purpose
GET /memory-overrides Effective value + env baseline + override flag
PUT /memory-overrides Set a system variable (takes effect on the very next request)
DELETE /memory-overrides Reset all memory system variables to their env defaults

Config (@Controller('configs'))

Per-session persisted workbench config (HarnessConfig — see 1.5):

Method Path Purpose
GET /configs/:sessionId Fetch the persisted config for a session (404 if none)
PUT /configs/:sessionId Upsert selectedModel, preprocessing, providerOverrides, memoryPartition, memoryCognition
DELETE /configs/:sessionId Delete the persisted config for a session

Qdrant (@Controller('qdrant'))

Long-term memory surfaces (vector store — see 1.5). Two spaces per user: the fact partition (memory_partition) and the AI's cognition document (memory_cognition).

Method Path Purpose
GET /qdrant/status Collection status (feature flag, existence, indexes)
GET /qdrant/memory List records; all query params are optional tightenings (memoryPartition / memoryCognition, session, role, tags, contains)
POST /qdrant/text Store a text verbatim as one memory record (sync); {accepted, id} envelope
DELETE /qdrant/text Delete by filters (text exact / contains / tags / conversationId / requestId — at least one matcher required, capped at 50 matches) or cognition=true to purge the AI's cognition space (profile + insights)
POST /qdrant/search/text Multi-variant semantic search (full text + per-sentence variants)
POST /qdrant/search/vector Search by a raw query vector
DELETE /qdrant/memory Prune a whole partition (facts AND cognition) or one conversation of it (facts only)

Conversations (@Controller('conversations'))

Conversation persistence (HarnessConversation — see 1.5):

Method Path Purpose
GET /conversations/:sessionId List conversations for a session
GET /conversations/:sessionId/:conversationId Get the latest state of one conversation
PUT /conversations/:sessionId/:conversationId/:requestId Upsert a conversation turn (title + content)
DELETE /conversations/:sessionId/:conversationId Delete a conversation and all its turns
DELETE /conversations/:sessionId/:conversationId/:requestId Delete one conversation turn

Stock data (@Controller('stock-data'))

Cached end-of-day market history (see 1.5 for the storage model). Reads come from Postgres first; missing coverage is backfilled from the configured market-data provider (EODHD) on access, so repeating ranges are free.

Method Path Purpose
GET /stock-data/history OHLCV bars for a ticker in the inclusive [from, to] window (YYYY-MM-DD; defaults: 92-day lookback → today). Gap-backfilled on access.
GET /stock-data/coverage Available date range for a ticker (backfilled to the 10-year retention on first access) — lets the chart's range controls size to real data.

These back the dashboard's stock-market response charts (see 2.2).

Sharp overrides (@Controller('sharp-overrides'))

Image preprocessing configuration and preview (see 1.5 / PProc):

Method Path Purpose
GET /sharp-overrides Current preprocessing configuration
PUT /sharp-overrides Update preprocessing configuration overrides
POST /sharp-overrides/preview Run an uploaded image through the current config, return variants

Health (@Controller('health'))

Method Path Purpose
GET /health/live Liveness: process memory/disk thresholds
GET /health/ready Readiness: PostgreSQL + MinIO indicators answer

Conventions

  • Every endpoint is described by @Api*() decorator composites (ApiTags, ApiOperation, ApiResponse, body/query schemas) — Swagger stays honest by construction.
  • Responses are DTO-typed (HarnessControllerResponse, CancelHarnessJobResponseDto, …) and validated at the boundary.
  • 202 Accepted everywhere work is handed to a queue — the API never blocks on model inference.

Clone this wiki locally