openapi: 3.0.1
info:
  title: Superlinked Server 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: Ingestion
    description: Schema-generated endpoints that accept records and write embeddings to the connected vector database.
  - name: Query
    description: Schema-generated endpoints that run registered queries against the connected vector database.
  - name: Data Loader
    description: Endpoints to trigger and monitor configured batch data loaders.
paths:
  /api/v1/ingest/{schema}:
    post:
      operationId: ingestRecords
      tags:
        - Ingestion
      summary: Ingest records for a schema
      description: >-
        Generated per schema declared in the Superlinked app. Accepts one or
        more records matching the schema's fields; the server computes
        multi-modal embeddings and persists them to the configured vector
        database. The {schema} path segment is the schema's id (for example,
        the lowercased schema class name).
      parameters:
        - name: schema
          in: path
          required: true
          description: Identifier of the Superlinked schema whose ingest endpoint is being called.
          schema:
            type: string
            example: paragraph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestRequest'
      responses:
        '202':
          description: Accepted. Records were received and embedding/persistence was scheduled.
        '422':
          description: Request body did not match the generated schema.
  /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.
  /data-loader/{name}/run:
    post:
      operationId: runDataLoader
      tags:
        - Data Loader
      summary: Trigger a configured data loader
      description: Starts a configured batch data loader to backfill vectors from a file or external source.
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the configured data loader.
          schema:
            type: string
            example: review
      responses:
        '202':
          description: Data loader run accepted.
  /data-loader/{name}/status:
    get:
      operationId: getDataLoaderStatus
      tags:
        - Data Loader
      summary: Get data loader status
      description: Reports the progress and state of a configured data loader.
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the configured data loader.
          schema:
            type: string
            example: review
      responses:
        '200':
          description: Current data loader status.
components:
  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.
  schemas:
    IngestRequest:
      type: object
      description: >-
        Record payload whose fields are generated from the target schema. Field
        names and types shown here are illustrative.
      additionalProperties: true
      example:
        id: doc-1
        body: Example text to embed.
        rating: 5
    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
    QueryResponse:
      type: object
      description: Ranked results from the connected vector database.
      properties:
        entries:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true