vecna/pkg/server/spec/openapi.yaml

openapi: "3.1.0"
info:
  title: vecna Embedding Adapter
  description: Proxies text to a backing embedding model and adapts the result vectors between dimensions.
  version: "1.0.0"

servers:
  - url: http://localhost:8080

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string

    OpenAIEmbedRequest:
      type: object
      required: [input, model]
      properties:
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        model:
          type: string

    OpenAIEmbedResponse:
      type: object
      properties:
        object:
          type: string
          example: list
        model:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              object:
                type: string
                example: embedding
              index:
                type: integer
              embedding:
                type: array
                items:
                  type: number
                  format: float
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            total_tokens:
              type: integer

    GoogleEmbedContentRequest:
      type: object
      required: [content]
      properties:
        content:
          type: object
          properties:
            parts:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
        taskType:
          type: string

    GoogleEmbedContentResponse:
      type: object
      properties:
        embedding:
          type: object
          properties:
            values:
              type: array
              items:
                type: number
                format: float

    GoogleBatchRequest:
      type: object
      required: [requests]
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/GoogleEmbedContentRequest'

    GoogleBatchResponse:
      type: object
      properties:
        embeddings:
          type: array
          items:
            type: object
            properties:
              values:
                type: array
                items:
                  type: number
                  format: float

  headers:
    X-Vecna-Forward-Ms:
      description: Time spent forwarding the request to the backing model (milliseconds).
      schema:
        type: integer
    X-Vecna-Translate-Ms:
      description: Time spent in the dimension adapter (milliseconds).
      schema:
        type: integer
    X-Vecna-Total-Ms:
      description: Total request wall-clock time (milliseconds).
      schema:
        type: integer

paths:
  /v1/embeddings:
    post:
      summary: OpenAI-compatible embeddings
      operationId: openaiEmbeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAIEmbedRequest'
      responses:
        "200":
          description: Adapted embeddings
          headers:
            X-Vecna-Forward-Ms:
              $ref: '#/components/headers/X-Vecna-Forward-Ms'
            X-Vecna-Translate-Ms:
              $ref: '#/components/headers/X-Vecna-Translate-Ms'
            X-Vecna-Total-Ms:
              $ref: '#/components/headers/X-Vecna-Total-Ms'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIEmbedResponse'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "502":
          description: Backing model error

  /v1/models/{model}:embedContent:
    post:
      summary: Google-compatible single embedContent
      operationId: googleEmbedContent
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleEmbedContentRequest'
      responses:
        "200":
          description: Adapted embedding
          headers:
            X-Vecna-Forward-Ms:
              $ref: '#/components/headers/X-Vecna-Forward-Ms'
            X-Vecna-Translate-Ms:
              $ref: '#/components/headers/X-Vecna-Translate-Ms'
            X-Vecna-Total-Ms:
              $ref: '#/components/headers/X-Vecna-Total-Ms'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleEmbedContentResponse'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "502":
          description: Backing model error

  /v1/models/{model}:batchEmbedContents:
    post:
      summary: Google-compatible batch batchEmbedContents
      operationId: googleBatchEmbedContents
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleBatchRequest'
      responses:
        "200":
          description: Adapted embeddings
          headers:
            X-Vecna-Forward-Ms:
              $ref: '#/components/headers/X-Vecna-Forward-Ms'
            X-Vecna-Translate-Ms:
              $ref: '#/components/headers/X-Vecna-Translate-Ms'
            X-Vecna-Total-Ms:
              $ref: '#/components/headers/X-Vecna-Total-Ms'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleBatchResponse'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "502":
          description: Backing model error