api.yaml

openapi: "3.0.0"
info:
  version: 0.5.6
  title: Tiny Systems API
  description: |
    Public [Tiny Systems](https://tinysystems.io/) API.

    All endpoints live under the `/v1/` prefix. The prefix is part of the
    stability contract: once an endpoint is published under `/v1/`, its
    path, method, request shape, and response shape cannot change in a
    breaking way. Breaking changes ship under a new major prefix (`/v2/`,
    etc.) alongside the old one for a deprecation window.

servers:
  - url: https://api.tinysystems.io
    description: Tiny Systems API server

paths:
  /v1/health:
    get:
      operationId: health-check
      tags:
        - healthcheck
      description: Health check endpoint
      security: []
      responses:
        200:
          description: Success

  /v1/devtools/publish-module:
    post:
      operationId: publish-module
      tags:
        - devtools
      description: |
        Registers module and returns credentials for push
      security:
        - DeveloperToken: []
      requestBody:
        description: Publish module request
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishModuleRequest"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishModuleResult"

  /v1/devtools/update-module-version:
    post:
      operationId: update-module-version
      tags:
        - devtools
      description: |
        Update module version with image information
      security:
        - DeveloperToken: []
      requestBody:
        description: Module Version ID, image information
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateModuleVersionRequest"
      responses:
        200:
          description: Success

  /v1/solutions/export:
    get:
      operationId: export-solution
      tags:
        - solutions
      summary: Export solution using one-time token
      description: |
        Returns solution export JSON. Requires a valid one-time token
        obtained via gRPC CreateExportToken.
      security: []
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: One-time export token
      responses:
        200:
          description: Solution export JSON
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        401:
          description: Invalid or expired token
        404:
          description: Solution not found

  /v1/solutions/search:
    get:
      operationId: search-public-solutions
      tags:
        - solutions
      summary: Search public solutions catalog
      description: |
        Search the public solutions catalog by keyword and/or tags.
        Returns summaries only — use `/v1/solutions/{uuid}` for the full
        structure including flows, nodes, and edges.

        When an embedding index is available server-side, semantic search
        runs first; otherwise the query falls back to keyword match on
        title, description, and tags. Only solutions marked `public=true`
        are returned regardless of caller authentication.
      security: []
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Keyword query matched against title, description, and tags
        - name: tags
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Tag filter; repeat the parameter for multiple tags
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Maximum results to return
      responses:
        200:
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolutionSearchResponse"

  /v1/modules/search:
    get:
      operationId: search-public-modules
      tags:
        - modules
      summary: Search the public module catalog
      description: |
        Search Tiny Systems' public module catalog by keyword. Returns the
        same slice that backs https://tinysystems.io/modules — modules with
        `public = true` and their latest version.

        Returns summaries only (name, description, latest version, facet
        flags). Use `/v1/modules/{name}` for the full detail payload
        including components, port schemas, RBAC permissions, and helm
        install instructions.

        This endpoint is the catalog counterpart to `list_modules` on the
        local MCP server: the latter lists modules already installed in
        the caller's cluster, while this one lists modules available to
        install.
      security: []
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Keyword query matched against module name and description
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Maximum results to return
      responses:
        200:
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModuleSearchResponse"

  /v1/modules/{name}:
    get:
      operationId: get-public-module
      tags:
        - modules
      summary: Get full details of a public module
      description: |
        Returns the complete PublicModuleDetails payload for a single
        module: description, latest version, components with port schemas,
        RBAC permissions, and the helm install configuration the desktop
        client / installer uses (chart repo, chart name, command template,
        prerequisites, warnings, storage/ingress requirements).

        `name` accepts either the base name (e.g. `common-module-v0`) or
        the full workspace-qualified name (e.g. `tinysystems/common-module-v0`).
        Private modules return 404 regardless of caller identity.
      security: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Module name (base or workspace-qualified)
      responses:
        200:
          description: Full module details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicModuleDetails"
        404:
          description: Module not found or not public

  /v1/solutions/{uuid}:
    get:
      operationId: get-public-solution
      tags:
        - solutions
      summary: Get full details of a public solution
      description: |
        Returns the complete `SolutionDetails` payload for a public
        solution: every flow with its nodes, edges, and configurations,
        plus any solution-level variables. Only solutions marked
        `public=true` are accessible anonymously; private solutions
        return 404.
      security: []
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
          description: Solution UUID
      responses:
        200:
          description: Full solution details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolutionDetails"
        404:
          description: Solution not found or not public

components:
  schemas:
    NodeStatisticsMap:
      type: object
      additionalProperties: {}

    PublishModuleResult:
      type: object
      properties:
        module:
          $ref: "#/components/schemas/PublishModuleVersion"
        options:
          $ref: "#/components/schemas/BuildPushOptions"
    PublishModuleVersion:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: string
      required:
        - id
        - name
        - version
    BuildPushOptions:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
        repo:
          type: string
        tag:
          type: string
      required:
        - username
        - password
        - repo
        - tag
    PublishModuleRequest:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        info:
          type: string
        description:
          type: string
        sdk_version:
          type: string
          description: SDK version used to build this module
        components:
          type: array
          items:
            $ref: '#/components/schemas/PublishComponent'
        requirements:
          $ref: '#/components/schemas/ModuleRequirements'
      required:
        - name
        - version
        - components
    ModuleRequirements:
      type: object
      properties:
        rbac:
          $ref: '#/components/schemas/RBACRequirements'
        storage:
          $ref: '#/components/schemas/StorageRequirements'
        bundles:
          type: array
          description: Third-party Helm releases the module can install alongside itself (e.g. embedding-module ships TEI, database-extension ships pgvector). Install UI exposes one toggle per bundle; enabled bundles get their own helm install in the same namespace.
          items:
            $ref: '#/components/schemas/BundledDependency'
        secrets:
          $ref: '#/components/schemas/SecretRequirements'
    SecretRequirements:
      type: object
      description: |
        Declares the k8s Secrets a module needs to read. Install UI
        prompts the user to supply the actual Secret names; chart
        Role's resourceNames is pinned to those values. Module code
        resolves placeholders via pkg/secret.Resolve at OnSettings
        time. Empty means the module consumes no Secrets and no
        Role is created.
      properties:
        names:
          type: array
          description: List of Secret names the module may reference (pre-flight allowlist).
          items:
            type: string
    BundledDependency:
      type: object
      description: A Helm release the module offers to provision on install. Author-declared values cover the common case; exposedSchema lets the user override a subset via the install form.
      required:
        - name
        - chartRepo
        - chartName
      properties:
        name:
          type: string
          description: Stable identifier — becomes the bundle's Helm release name and the install-form checkbox label.
        description:
          type: string
          description: Shown next to the checkbox in the install UI.
        chartRepo:
          type: string
          description: Helm repository URL.
        chartName:
          type: string
          description: Chart name within the repo.
        chartVersion:
          type: string
          description: Pinned chart version. Empty means use latest at install time (not recommended).
        defaultEnabled:
          type: boolean
          description: Whether the install-form checkbox starts checked.
        connectionHint:
          type: string
          description: Hint shown to the user about how the module reaches the bundle — typically the in-cluster Service URL (e.g. http://tei.tei.svc.cluster.local:80) and which module setting field receives it.
        values:
          type: object
          description: Author-supplied default values passed to the bundle's chart. Map of any-typed values. Merged on top of chart defaults at install time, then overlaid by user overrides.
        exposedSchema:
          type: object
          description: JSON Schema fragment defining which value keys the install form exposes as user-editable fields. Same renderer the flow editor uses. Empty means the bundle is install-as-is, no user knobs.
        valuesYAML:
          type: string
          description: Optional raw values.yaml content for complex bundles where the structured values map is awkward. Merged before values map (which takes precedence).
    StorageRequirements:
      type: object
      description: Persistent storage needs declared by the module. When enabled, the install flow exposes storage-size / storage-class fields and the helm command includes the PVC switches.
      properties:
        enabled:
          type: boolean
          description: True when the module requires a PVC to function (e.g. file-backed embedded stores).
        size:
          type: string
          description: Default storage size suggestion (e.g. 1Gi, 10Gi). Author hint; UI lets the operator override.
        storageClassName:
          type: string
          description: Default storage class suggestion. Empty uses the cluster default.
    RBACRequirements:
      type: object
      properties:
        enableKubernetesResourceAccess:
          type: boolean
          description: Enable access to pods, services, deployments, ingresses
        extraRules:
          type: array
          items:
            $ref: '#/components/schemas/RBACRule'
    RBACRule:
      type: object
      properties:
        apiGroups:
          type: array
          items:
            type: string
        resources:
          type: array
          items:
            type: string
        verbs:
          type: array
          items:
            type: string
    PublishComponent:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        info:
          type: string
        tags:
          type: array
          items:
            type: string
        ports:
          type: array
          items:
            $ref: '#/components/schemas/PublishComponentPort'
      required:
        - name
        - description
    PublishComponentPort:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        source:
          type: boolean
        position:
          type: integer
        schema:
          type: object
          additionalProperties: {}
        default_data:
          type: object
          additionalProperties: {}
      required:
        - name
        - source
    UpdateModuleVersionRequest:
      type: object
      properties:
        id:
          type: string
          description: Module Version ID
        repo:
          type: string
          description: Image repo
        tag:
          type: string
          description: Image tag
      required:
        - id
        - repo
        - tag

    SolutionSummary:
      type: object
      description: |
        Brief overview of a solution returned by `/v1/solutions/search`.
        Carries enough for the caller to render a result row and decide
        whether to fetch the full details.
      properties:
        uuid:
          type: string
          description: Stable solution identifier, used with `/v1/solutions/{uuid}`
        title:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
      required:
        - uuid
        - title
        - description

    SolutionSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SolutionSummary"
      required:
        - results

    SolutionDetails:
      type: object
      description: |
        Full solution structure returned by `/v1/solutions/{uuid}`.
        Contains every flow with its nodes, edges, and configurations,
        plus any solution-level variables.
      properties:
        uuid:
          type: string
        title:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        flows:
          type: array
          items:
            $ref: "#/components/schemas/SolutionFlow"
        variables:
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
        - uuid
        - title
        - description
        - flows

    SolutionFlow:
      type: object
      properties:
        title:
          type: string
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/SolutionNode"
        edges:
          type: array
          items:
            $ref: "#/components/schemas/SolutionEdge"
      required:
        - title
        - nodes
        - edges

    SolutionNode:
      type: object
      properties:
        id:
          type: string
        component:
          type: string
        module:
          type: string
        settings:
          type: object
          additionalProperties: {}
        position:
          type: object
          additionalProperties: {}
      required:
        - id
        - component
        - module

    SolutionEdge:
      type: object
      properties:
        source:
          type: string
        source_handle:
          type: string
        target:
          type: string
        target_handle:
          type: string
        configuration:
          type: object
          additionalProperties: {}
      required:
        - source
        - source_handle
        - target
        - target_handle

    PublicModuleSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/PublicModuleSummary"
      required:
        - results

    PublicModuleSummary:
      type: object
      description: |
        Lightweight module entry returned by `/v1/modules/search`. Carries
        enough for the caller to choose a module to install; follow up
        with `/v1/modules/{name}` for components and install instructions.
      properties:
        name:
          type: string
          description: Workspace-qualified module name (e.g. "tinysystems/common-module-v0")
        full_name:
          type: string
          description: Human-readable display name
        description:
          type: string
        verified:
          type: boolean
          description: Whether the module has been verified by Tiny Systems
        latest_version:
          $ref: "#/components/schemas/PublicModuleVersionSummary"
      required:
        - name
        - description

    PublicModuleVersionSummary:
      type: object
      properties:
        version:
          type: string
        sdk_version:
          type: string
        requires_kubernetes_access:
          type: boolean
          description: Module needs RBAC access to the Kubernetes API
      required:
        - version

    PublicModuleDetails:
      type: object
      description: |
        Full module payload returned by `/v1/modules/{name}`. Equivalent
        to the summary plus the full latest version, every component with
        port schemas, the RBAC permissions the module needs, and the helm
        install configuration that desktop/local installers use.
      properties:
        name:
          type: string
        full_name:
          type: string
        description:
          type: string
        verified:
          type: boolean
        latest_version:
          $ref: "#/components/schemas/PublicModuleVersionDetails"
        helm_install:
          $ref: "#/components/schemas/HelmInstallConfig"
      required:
        - name
        - description

    PublicModuleVersionDetails:
      type: object
      properties:
        version:
          type: string
        sdk_version:
          type: string
        release_notes:
          type: string
        repo:
          type: string
          description: Container image repository
        tag:
          type: string
          description: Container image tag
        requires_kubernetes_access:
          type: boolean
        components:
          type: array
          items:
            $ref: "#/components/schemas/PublicModuleComponent"
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/PublicModulePermission"
        bundles:
          type: array
          description: |
            Third-party Helm releases the module declares for install-time
            provisioning. Same shape as ModuleRequirements.bundles. Empty
            (or absent) for modules that don't bundle anything.
          items:
            $ref: "#/components/schemas/BundledDependency"
      required:
        - version
        - components

    PublicModuleComponent:
      type: object
      description: |
        A component inside a module: its name, the description and info
        the component author wrote, its tags, and the typed ports it
        exposes.
      properties:
        name:
          type: string
          description: Component identifier (e.g. "ticker", "http_server")
        description:
          type: string
        info:
          type: string
          description: Author-written operational notes; the LLM should read this before wiring the component
        tags:
          type: array
          items:
            type: string
        ports:
          type: array
          items:
            $ref: "#/components/schemas/PublicModulePort"
      required:
        - name

    PublicModulePort:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          description: "source or target"
          enum:
            - source
            - target
        schema:
          type: object
          additionalProperties: {}
          description: JSON Schema describing the port's data shape
        default_data:
          type: object
          additionalProperties: {}
          description: Sample data for the port, usable as example input
      required:
        - name
        - type

    PublicModulePermission:
      type: object
      description: Kubernetes RBAC rule required by the module
      properties:
        api_groups:
          type: array
          items:
            type: string
        resources:
          type: array
          items:
            type: string
        verbs:
          type: array
          items:
            type: string

    HelmInstallConfig:
      type: object
      description: |
        Helm installation instructions the caller can render verbatim.
        The `command` field is a copy-pasteable template with placeholders
        (e.g. `<NAMESPACE>`) that map to entries in `fields`. Prerequisites
        and warnings are plain strings meant for display.
      properties:
        command:
          type: string
          description: Helm install command template with placeholders
        fields:
          type: array
          items:
            $ref: "#/components/schemas/HelmConfigField"
        prerequisites:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
        requires_ingress:
          type: boolean
        requires_storage:
          type: boolean
        chart_repo:
          type: string
        chart_name:
          type: string
        bundles:
          type: array
          description: |
            Self-contained helm install snippets for each third-party
            release the module declared. UI renders a checkbox per
            entry; checked bundles' commands get appended to the
            module command before paste.
          items:
            $ref: "#/components/schemas/HelmBundle"

    HelmBundle:
      type: object
      description: |
        Selector into the operator chart's curated subchart set. Name
        must match a registered subchart alias (e.g. "tei", "pgvector").
        When the user ticks the bundle's checkbox in the install UI,
        the bundle's set_flags get appended to the module helm command —
        one release, one upgrade unit, helm-tracked lifecycle.
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        default_enabled:
          type: boolean
        connection_hint:
          type: string
          description: |
            Free-form note telling the module how to reach this bundle
            once installed (e.g. "DATABASE_URL=postgres://...").
        set_flags:
          type: array
          description: |
            Author defaults rendered as --set flags (e.g.
            "--set bundles.tei.image.tag=cpu-1.5"). UI appends these
            for every ticked bundle, alongside "--set bundles.<name>.enabled=true".
          items:
            type: string
        exposed_schema:
          type: object
          additionalProperties: {}
          description: JSON Schema fragment driving per-bundle form fields on the install page

    HelmConfigField:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        description:
          type: string
        default_value:
          type: string
        placeholder:
          type: string
        required:
          type: boolean
        type:
          type: string
          description: "text or select"
        options:
          type: array
          items:
            type: string

  securitySchemes:
    DeveloperToken:
      type: http
      scheme: bearer
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: [ ]