openapi: 3.0.1
info:
  title: Superlinked Server Data Loader Query API
  description: REST API auto-generated by the Superlinked Server from a Superlinked app's schema, index, and query definitions. The Superlinked open-source Python framework (Apache-2.0) lets you declare Schema, Space, Index, Query, Source, and Executor objects; when run with a RestExecutor / RestApp the server exposes ingestion and query endpoints whose exact paths and request bodies are derived from those definitions. This document models the generated pattern using representative, templated path and body names ({schema}, {query_name}); the concrete endpoints on any given deployment depend on the app's own schema and registered queries. The framework repository was archived on 2026-05-29 as the team shifted to the Superlinked Inference Engine; the server REST pattern documented here reflects the framework as last published.
  termsOfService: https://www.superlinked.com
  contact:
    name: Superlinked
    url: https://www.superlinked.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '1.0'
servers:
- url: http://localhost:8080
  description: Default local Superlinked Server. Replace with your deployed host or Superlinked Cloud endpoint.
tags:
- name: Query
  description: Schema-generated endpoints that run registered queries against the connected vector database.
paths:
  /api/v1/search/{query_name}:
    post:
      operationId: runQuery
      tags:
      - Query
      summary: Run a registered query
      description: Generated per RestQuery registered in the Superlinked app. The request body parameters (for example natural_query, limit, and any query-time weights or filters) are derived from the query definition. Returns ranked entries from the connected vector store, optionally with metadata.
      parameters:
      - name: query_name
        in: path
        required: true
        description: Name of the registered RestQuery to execute.
        schema:
          type: string
          example: paragraph_query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Ranked query results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '422':
          description: Request body did not match the generated query parameters.
components:
  schemas:
    QueryResponse:
      type: object
      description: Ranked results from the connected vector database.
      properties:
        entries:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    QueryRequest:
      type: object
      description: Query parameters generated from the registered RestQuery. Parameter names shown here are illustrative; actual parameters depend on the query definition.
      properties:
        natural_query:
          type: string
          description: Natural-language query string, when the query defines one.
        limit:
          type: integer
          description: Maximum number of results to return.
      additionalProperties: true
      example:
        natural_query: comfortable hotel near the beach
        limit: 10
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional API key header. The open-source Superlinked Server ships without built-in auth; deployments commonly place an API key or bearer token check in front of it (gateway or custom middleware). Configure to match your deployment.
    bearerAuth:
      type: http
      scheme: bearer
      description: Optional bearer token, when the deployment fronts the server with token auth.