Feldera Platform API

openapi: 3.2.0
info:
  title: Feldera Platform API
  description: With Feldera, users create data pipelines out of SQL programs.
  contact:
    name: Feldera Team
    email: dev@feldera.com
  license:
    name: MIT OR Apache-2.0
  version: 0.323.0
tags:
- name: Platform
paths:
  /config/authentication:
    get:
      tags:
      - Platform
      summary: Get Auth Config
      description: Retrieve the authentication provider configuration.
      operationId: get_config_authentication
      responses:
        '200':
          description: The response body contains Authentication Provider configuration, or is empty if no auth is configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProvider'
        '500':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/api_keys:
    get:
      tags:
      - Platform
      summary: List API Keys
      description: Retrieve a list of your API keys.
      operationId: list_api_keys
      responses:
        '200':
          description: API keys retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyDescr'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
    post:
      tags:
      - Platform
      summary: Create API Key
      description: 'Create a new API key with the specified name. The generated API key

        will be returned in the response and cannot be retrieved again later.'
      operationId: post_api_key
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewApiKeyRequest'
        required: true
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewApiKeyResponse'
        '409':
          description: API key with that name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: An entity with this name already exists
                error_code: DuplicateName
                details: null
      security:
      - JSON web token (JWT) or API key: []
  /v0/api_keys/{api_key_name}:
    get:
      tags:
      - Platform
      summary: Get API Key
      description: Retrieve the metadata of a specific API key by its name.
      operationId: get_api_key
      parameters:
      - name: api_key_name
        in: path
        description: Unique API key name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyDescr'
        '404':
          description: API key with that name does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unknown API key 'non-existent-api-key'
                error_code: UnknownApiKey
                details:
                  name: non-existent-api-key
      security:
      - JSON web token (JWT) or API key: []
    delete:
      tags:
      - Platform
      summary: Delete API Key
      description: Remove an API key by its name.
      operationId: delete_api_key
      parameters:
      - name: api_key_name
        in: path
        description: Unique API key name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key deleted successfully
        '404':
          description: API key with that name does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unknown API key 'non-existent-api-key'
                error_code: UnknownApiKey
                details:
                  name: non-existent-api-key
      security:
      - JSON web token (JWT) or API key: []
  /v0/cluster/events:
    get:
      tags:
      - Platform
      summary: List Cluster Events
      description: 'Retrieve a list of retained cluster monitor events ordered from most recent to least recent.


        The returned events only have limited details, the full details can be retrieved using

        the `GET /v0/cluster/events/` endpoint.


        Cluster monitor events are collected at a periodic interval (every 10s), however only

        every 10 minutes or if the overall health changes, does it get inserted into the database

        (and thus, served by this endpoint). At most 1000 events are retained (newest first),

        and events older than 72h are deleted. The latest event, if it already exists, is never

        cleaned up.'
      operationId: list_cluster_events
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClusterMonitorEventSelectedInfo'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
  /v0/cluster/events/{event_id}:
    get:
      tags:
      - Platform
      summary: Get Cluster Event
      description: 'Get specific cluster monitor event.


        The identifiers of the events can be retrieved via `GET /v0/cluster/events`.

        At most 1000 events are retained (newest first), and events older than 72h are deleted.

        The latest event, if it already exists, is never cleaned up.

        This endpoint can return a 404 for an event that no longer exists due to clean-up.'
      operationId: get_cluster_event
      parameters:
      - name: event_id
        in: path
        description: Cluster monitor event identifier or `latest`
        required: true
        schema:
          type: string
      - name: selector
        in: query
        description: 'The `selector` parameter limits which fields are returned.

          Limiting which fields is particularly handy for instance when frequently

          monitoring over low bandwidth connections while being only interested

          in status.'
        required: false
        schema:
          $ref: '#/components/schemas/ClusterMonitorEventFieldSelector'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterMonitorEventSelectedInfo'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
  /v0/cluster_healthz:
    get:
      tags:
      - Platform
      summary: Check Cluster Health
      description: Determine the latest cluster health via the latest cluster monitor event.
      operationId: get_cluster_health
      responses:
        '200':
          description: All services healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '503':
          description: One or more services unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
      security:
      - JSON web token (JWT) or API key: []
  /v0/config:
    get:
      tags:
      - Platform
      summary: Get Platform Config
      description: Retrieve configuration of the Feldera Platform.
      operationId: get_config
      responses:
        '200':
          description: The response body contains basic configuration information about this host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
        '500':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
  /v0/config/demos:
    get:
      tags:
      - Platform
      summary: List Demos
      description: Retrieve the list of demos available in the WebConsole.
      operationId: get_config_demos
      responses:
        '200':
          description: List of demos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Demo'
        '500':
          description: Failed to read demos from the demos directories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
  /v0/config/session:
    get:
      tags:
      - Platform
      summary: Get Session
      description: Retrieve login session information for your current user session.
      operationId: get_config_session
      responses:
        '200':
          description: The response body contains current session information including tenant details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionInfo'
        '500':
          description: Request failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - JSON web token (JWT) or API key: []
components:
  schemas:
    ClusterMonitorEventSelectedInfo:
      type: object
      description: 'Cluster monitor event information which has a selected subset of optional fields.

        If an optional field is not selected (i.e., is `None`), it will not be serialized.'
      required:
      - id
      - recorded_at
      - all_healthy
      - api_status
      - compiler_status
      - runner_status
      properties:
        all_healthy:
          type: boolean
        api_resources_info:
          type:
          - string
          - 'null'
        api_self_info:
          type:
          - string
          - 'null'
        api_status:
          $ref: '#/components/schemas/MonitorStatus'
        compiler_resources_info:
          type:
          - string
          - 'null'
        compiler_self_info:
          type:
          - string
          - 'null'
        compiler_status:
          $ref: '#/components/schemas/MonitorStatus'
        id:
          $ref: '#/components/schemas/ClusterMonitorEventId'
        recorded_at:
          type: string
          format: date-time
        runner_resources_info:
          type:
          - string
          - 'null'
        runner_self_info:
          type:
          - string
          - 'null'
        runner_status:
          $ref: '#/components/schemas/MonitorStatus'
    ClusterMonitorEventId:
      type: string
      format: uuid
      description: Cluster monitor event identifier.
    LicenseValidity:
      oneOf:
      - type: object
        required:
        - Exists
        properties:
          Exists:
            $ref: '#/components/schemas/LicenseInformation'
      - type: object
        required:
        - DoesNotExistOrNotConfirmed
        properties:
          DoesNotExistOrNotConfirmed:
            type: string
            description: 'Either the license key is invalid according to the server, or the request that checks with

              the server failed (e.g., if it could not reach the server).'
    ProviderGenericOidc:
      type: object
      required:
      - issuer
      - client_id
      - extra_oidc_scopes
      properties:
        client_id:
          type: string
        extra_oidc_scopes:
          type: array
          items:
            type: string
        issuer:
          type: string
    ApiKeyDescr:
      type: object
      description: API key descriptor.
      required:
      - id
      - name
      - scopes
      properties:
        id:
          $ref: '#/components/schemas/ApiKeyId'
        name:
          type: string
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/ApiPermission'
    ProviderAwsCognito:
      type: object
      required:
      - issuer
      - login_url
      - logout_url
      properties:
        issuer:
          type: string
        login_url:
          type: string
        logout_url:
          type: string
    AuthProvider:
      oneOf:
      - type: object
        required:
        - AwsCognito
        properties:
          AwsCognito:
            $ref: '#/components/schemas/ProviderAwsCognito'
      - type: object
        required:
        - GenericOidc
        properties:
          GenericOidc:
            $ref: '#/components/schemas/ProviderGenericOidc'
    NewApiKeyRequest:
      type: object
      description: Request to create a new API key.
      required:
      - name
      properties:
        name:
          type: string
          description: Key name.
          example: my-api-key
    ErrorResponse:
      type: object
      description: Information returned by REST API endpoints on error.
      required:
      - message
      - error_code
      - details
      properties:
        details:
          description: 'Detailed error metadata.

            The contents of this field is determined by `error_code`.'
        error_code:
          type: string
          description: Error code is a string that specifies this error type.
          example: CodeSpecifyingErrorType
        message:
          type: string
          description: Human-readable error message.
          example: Explanation of the error that occurred.
    BuildInformation:
      type: object
      description: Information about the build of the platform.
      required:
      - build_timestamp
      - build_cpu
      - build_os
      - cargo_dependencies
      - cargo_features
      - cargo_debug
      - cargo_opt_level
      - cargo_target_triple
      - rustc_version
      properties:
        build_cpu:
          type: string
          description: CPU of build machine.
        build_os:
          type: string
          description: OS of build machine.
        build_timestamp:
          type: string
          description: Timestamp of the build.
        cargo_debug:
          type: string
          description: Whether the build is optimized for performance.
        cargo_dependencies:
          type: string
          description: Dependencies used during the build.
        cargo_features:
          type: string
          description: Features enabled during the build.
        cargo_opt_level:
          type: string
          description: Optimization level of the build.
        cargo_target_triple:
          type: string
          description: Target triple of the build.
        rustc_version:
          type: string
          description: Rust version of the build used.
    Configuration:
      type: object
      required:
      - telemetry
      - edition
      - version
      - revision
      - runtime_revision
      - changelog_url
      - build_info
      - build_source
      properties:
        build_info:
          $ref: '#/components/schemas/BuildInformation'
        build_source:
          type: string
          description: 'Build source: "ci" for GitHub Actions builds, "source" for local builds'
        changelog_url:
          type: string
          description: URL that navigates to the changelog of the current version
        edition:
          type: string
          description: 'Feldera edition: "Open source" or "Enterprise"'
        license_validity:
          allOf:
          - $ref: '#/components/schemas/LicenseValidity'
        revision:
          type: string
          description: Specific revision corresponding to the edition `version` (e.g., git commit hash).
        runtime_revision:
          type: string
          description: Specific revision corresponding to the default runtime version of the platform (e.g., git commit hash).
        telemetry:
          type: string
          description: Telemetry key.
        unstable_features:
          type:
          - string
          - 'null'
          description: List of unstable features that are enabled.
        update_info:
          allOf:
          - $ref: '#/components/schemas/UpdateInformation'
        version:
          type: string
          description: 'The version corresponding to the type of `edition`.

            Format is `x.y.z`.'
    MonitorStatus:
      type: string
      enum:
      - InitialUnhealthy
      - Unhealthy
      - Healthy
    LicenseInformation:
      type: object
      required:
      - current
      - is_trial
      - description_html
      - remind_schedule
      properties:
        current:
          type: string
          format: date-time
          description: Timestamp when the server responded.
        description_html:
          type: string
          description: Optional description of the advantages of extending the license / upgrading from a trial
        extension_url:
          type:
          - string
          - 'null'
          description: URL that navigates the user to extend / upgrade their license
        is_trial:
          type: boolean
          description: Whether the license is a trial
        remind_schedule:
          $ref: '#/components/schemas/DisplaySchedule'
        remind_starting_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp from which the user should be reminded of the license expiring soon
        valid_until:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp at which point the license expires
    HealthStatus:
      type: object
      required:
      - all_healthy
      - api
      - compiler
      - runner
      properties:
        all_healthy:
          type: boolean
        api:
          $ref: '#/components/schemas/ServiceStatus'
        compiler:
          $ref: '#/components/schemas/ServiceStatus'
        runner:
          $ref: '#/components/schemas/ServiceStatus'
    ServiceStatus:
      type: object
      required:
      - healthy
      - message
      - unchanged_since
      - checked_at
      properties:
        checked_at:
          type: string
          format: date-time
        healthy:
          type: boolean
        message:
          type: string
        unchanged_since:
          type: string
          format: date-time
    ClusterMonitorEventFieldSelector:
      type: string
      enum:
      - all
      - status
    UpdateInformation:
      type: object
      required:
      - latest_version
      - is_latest_version
      - instructions_url
      - remind_schedule
      properties:
        instructions_url:
          type: string
          description: URL that navigates the user to instructions on how to update their deployment's version
        is_latest_version:
          type: boolean
          description: Whether the current version matches the latest version
        latest_version:
          type: string
          description: Latest version corresponding to the edition
        remind_schedule:
          $ref: '#/components/schemas/DisplaySchedule'
    SessionInfo:
      type: object
      required:
      - tenant_id
      - tenant_name
      properties:
        tenant_id:
          $ref: '#/components/schemas/TenantId'
        tenant_name:
          type: string
          description: Current user's tenant name
    Demo:
      type: object
      required:
      - name
      - title
      - description
      - program_code
      - udf_rust
      - udf_toml
      properties:
        description:
          type: string
          description: Description of the demo (parsed from SQL preamble).
        name:
          type: string
          description: Name of the demo (parsed from SQL preamble).
        program_code:
          type: string
          description: Program SQL code.
        title:
          type: string
          description: Title of the demo (parsed from SQL preamble).
        udf_rust:
          type: string
          description: User defined function (UDF) Rust code.
        udf_toml:
          type: string
          description: User defined function (UDF) TOML dependencies.
    NewApiKeyResponse:
      type: object
      description: Response to a successful API key creation.
      required:
      - id
      - name
      - api_key
      properties:
        api_key:
          type: string
          description: 'Generated secret API key. There is no way to retrieve this

            key again through the API, so store it securely.'
          example: apikey:v5y5QNtlPNVMwkmNjKwFU8bbIu5lMge3yHbyddxAOdXlEo84SEoNn32DUhQaf1KLeI9aOOfnJjhQ1pYzMrU4wQXON6pm6BS7Zgzj46U2b8pwz1280vYBEtx41hiDBRP
        id:
          $ref: '#/components/schemas/ApiKeyId'
        name:
          type: string
          description: API key name provided by the user.
          example: my-api-key
    ApiKeyId:
      type: string
      format: uuid
      description: API key identifier.
    ApiPermission:
      type: string
      description: Permission types for invoking API endpoints.
      enum:
      - Read
      - Write
    TenantId:
      type: string
      format: uuid
    DisplaySchedule:
      oneOf:
      - type: string
        description: 'Display it only once: after dismissal do not show it again'
        enum:
        - Once
      - type: string
        description: Display it again the next session if it is dismissed
        enum:
        - Session
      - type: object
        required:
        - Every
        properties:
          Every:
            type: object
            description: Display it again after a certain period of time after it is dismissed
            required:
            - seconds
            properties:
              seconds:
                type: integer
                format: int64
                minimum: 0
      - type: string
        description: Always display it, do not allow it to be dismissed
        enum:
        - Always
  securitySchemes:
    JSON_web_token__JWT__or_API_key:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Use a JWT token obtained via an OAuth2/OIDC\n                               login workflow or an API key obtained via\n                               the `/v0/api-keys` endpoint."