From 2fe01bde7d0b8ebdaee867d21b4446c7a8fea3df Mon Sep 17 00:00:00 2001
From: Becky Conning <becky.conning@icloud.com>
Date: Fri, 5 Jun 2026 18:18:26 +0100
Subject: [PATCH] pretext: spec POST /pipelines/{id}/encode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the new tenant-authed query-embedding route added in
precog/services#3504. Body is `{"text": "..."}` and the response is
the verbatim encoder envelope (`{"vec":[...],"dim":768,"model_id":"..."}`).

Slotted next to the vectorize PUT — same auth model, same family.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 reference/public-http-api.yaml | 87 ++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/reference/public-http-api.yaml b/reference/public-http-api.yaml
index 71481d6..fcaae41 100644
--- a/reference/public-http-api.yaml
+++ b/reference/public-http-api.yaml
@@ -1092,6 +1092,93 @@ paths:
                     are equivalent: the pipeline does not vectorize.
               required:
                 - vectorize
+  '/pipelines/{pipeline-id}/encode':
+    parameters:
+      - schema:
+          type: string
+        name: pipeline-id
+        in: path
+        required: true
+    post:
+      summary: Embed query text against the pipeline's vector model.
+      tags: []
+      operationId: post-pipelines-pipeline-id-encode
+      description: >-
+        Embed a piece of text using the same sentence-transformers
+        all-mpnet-base-v2 model that vectorized the pipeline's PRETEXT
+        corpus. The returned 768-dimensional vector is L2-normalized and
+        exact-parity with `PRETEXT.vec`, so the caller can plug it into a
+        `VECTOR_COSINE_SIMILARITY` scan against the same destination
+        without any re-normalization.
+
+        Intended for query-side embedding from external clients (e.g. an
+        MCP server's semantic_search tool) so they don't have to load the
+        model themselves. Tenant auth applies as on every other
+        `/pipelines/{id}/*` route: the caller must be able to see the
+        pipeline.
+
+        Internally a thin proxy to the in-cluster vectorizer-encoder
+        service; a 502 indicates the encoder service is unreachable or
+        returned non-2xx.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                text:
+                  type: string
+                  description: >-
+                    The query text to embed. Must be non-empty after
+                    trimming; an empty / whitespace-only string is
+                    rejected with 400.
+              required:
+                - text
+      responses:
+        '200':
+          description: Embedding produced successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  vec:
+                    type: array
+                    items:
+                      type: number
+                    description: >-
+                      The 768-dimensional L2-normalized embedding vector
+                      for the supplied text.
+                  dim:
+                    type: integer
+                    description: Dimensionality of the returned vector (always 768 for the current model).
+                  model_id:
+                    type: string
+                    description: >-
+                      Identifier of the embedding model that produced this
+                      vector. Always matches the `model_id` column of rows
+                      in the pipeline's PRETEXT table when the pipeline is
+                      vectorized.
+                required:
+                  - vec
+                  - dim
+                  - model_id
+        '400':
+          description: Empty or whitespace-only text.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error-message'
+        '401':
+          description: Unauthorized
+        '404':
+          description: Pipeline not found
+        '502':
+          description: Upstream encoder service returned a non-success response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error-message'
   '/pipelines/{pipeline-id}/semantic-contexts':
     parameters:
       - schema: