openapi: 3.0.3 info: title: Feldera Input Connectors Platform API description: "\nWith Feldera, users create data pipelines out of SQL programs.\nA SQL program comprises tables and views, and includes as well the definition of\ninput and output connectors for each respectively. A connector defines a data\nsource or data sink to feed input data into tables or receive output data\ncomputed by the views respectively.\n\n## Pipeline\n\nThe API is centered around the **pipeline**, which most importantly consists\nout of the SQL program, but also has accompanying metadata and configuration parameters\n(e.g., compilation profile, number of workers, etc.).\n\n* A pipeline is identified and referred to by its user-provided unique name.\n* The pipeline program is asynchronously compiled when the pipeline is first created or\n when its program is subsequently updated.\n* Pipeline deployment start is only able to proceed to provisioning once the program is successfully\n compiled.\n* A pipeline cannot be updated while it is deployed.\n\n## Concurrency\n\nEach pipeline has a version, which is incremented each time its core fields are updated.\nThe version is monotonically increasing. There is additionally a program version which covers\nonly the program-related core fields, and is used by the compiler to discern when to recompile.\n\n## Client request handling\n\n### Request outcome expectations\n\nThe outcome of a request is that it either fails (e.g., DNS lookup failed) without any response\n(no status code nor body), or it succeeds and gets back a response status code and body.\n\nIn case of a response, usually it is the Feldera endpoint that generated it:\n- If it is success (2xx), it will return whichever body belongs to the success response.\n- Otherwise, if it is an error (4xx, 5xx), it will return a Feldera error response JSON body\n which will have an application-level `error_code`.\n\nHowever, there are two notable exceptions when the response is not generated by the Feldera\nendpoint:\n- If the HTTP server, to which the endpoint belongs, encountered an issue, it might return\n 4xx (e.g., for an unknown endpoint) or 5xx error codes by itself (e.g., when it is initializing).\n- If the Feldera API server is behind a (reverse) proxy, the proxy can return error codes by itself,\n for example BAD GATEWAY (502) or GATEWAY TIMEOUT (504).\n\nAs such, it is not guaranteed that the (4xx, 5xx) will have a Feldera error response JSON body\nin these latter cases.\n\n### Error handling and retrying\n\nThe error type returned by the client should distinguish between the error responses generated\nby Feldera endpoints themselves (which have a Feldera error response body) and those that are\ngenerated by other sources.\n\nIn order for a client operation (e.g., `pipeline.resume()`) to be robust (i.e., not fail due to\na single HTTP request not succeeding) the client should use a retry mechanism if the operation\nis idempotent. The retry mechanism must however have a time limit, after which it times out.\nThis guarantees that the client operation is eventually responsive, which enables the script\nit is a part of to not hang indefinitely on Feldera operations and instead be able to decide\nby itself whether and how to proceed. If no response is returned, the mechanism should generally\nretry. When a response is returned, the decision whether to retry can generally depend on the status\ncode: especially the status codes 408, 502, 503 and 504 should be considered as transient errors.\nFiner grained retry decisions should be made by taking into account the application-level\n`error_code` if the response body was indeed a Feldera error response body.\n\n## Feldera client errors (4xx)\n\n_Client behavior:_ clients should generally return with an error when they get back a 4xx status\ncode, as it usually means the request will likely not succeed even if it is sent again. Certain\nrequests might make use of a timed retry mechanism when the client error is transient without\nrequiring any user intervention to overcome, for instance a transaction already being in progress\nleading to a temporary CONFLICT (409) error.\n\n- **BAD REQUEST (400)**: invalid user request (general).\n - _Example:_ the new pipeline name `example1@~` contains invalid characters.\n\n- **UNAUTHORIZED (401)**: the user is not authorized to issue the request.\n - _Example:_ an invalid API key is provided.\n\n- **NOT FOUND (404)**: a resource required to exist in order to process the request was not found.\n - _Example:_ a pipeline named `example` does not exist when trying to update it.\n\n- **CONFLICT (409)**: there is a conflict between the request and a relevant resource.\n - _Example:_ a pipeline named `example` already exists.\n - _Example:_ another transaction is already in process.\n\n## Feldera server errors (5xx)\n\n- **INTERNAL SERVER ERROR (500)**: the server is unexpectedly unable to process the request\n (general).\n - _Example:_ unable to reach the database.\n - _Client behavior:_ immediately return with an error.\n\n- **NOT IMPLEMENTED (501)**: the server does not implement functionality required to process the\n request.\n - _Example:_ making a request to an enterprise-only endpoint in the OSS edition.\n - _Client behavior:_ immediately return with an error.\n\n- **SERVICE UNAVAILABLE (503)**: the server is not (yet) able to process the request.\n - _Example:_ pausing a pipeline which is still provisioning.\n - _Client behavior:_ depending on the type of request, client may use a timed retry mechanism.\n\n## Feldera error response body\n\nWhen the Feldera API returns an HTTP error status code (4xx, 5xx), the body will contain the\nfollowing JSON object:\n\n```json\n{\n \"message\": \"Human-readable explanation.\",\n \"error_code\": \"CodeSpecifyingError\",\n \"details\": {\n\n }\n}\n```\n\nIt contains the following fields:\n- **message (string)**: human-readable explanation of the error that occurred and potentially\n hinting what can be done about it.\n- **error_code (string)**: application-level code about the error that occurred, written in CamelCase.\n For example: `UnknownPipelineName`, `DuplicateName`, `PauseWhileNotProvisioned`, ... .\n- **details (object)**: JSON object corresponding to the `error_code` with fields that provide\n details relevant to it. For example: if a name is unknown, a field with the unknown name in\n question.\n" 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: ClusterMonitorEventFieldSelector: type: string enum: - all - status 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 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 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 nullable: true api_self_info: type: string nullable: true api_status: $ref: '#/components/schemas/MonitorStatus' compiler_resources_info: type: string nullable: true compiler_self_info: type: string nullable: true compiler_status: $ref: '#/components/schemas/MonitorStatus' id: $ref: '#/components/schemas/ClusterMonitorEventId' recorded_at: type: string format: date-time runner_resources_info: type: string nullable: true runner_self_info: type: string nullable: true runner_status: $ref: '#/components/schemas/MonitorStatus' 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' 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. AuthProvider: oneOf: - type: object required: - AwsCognito properties: AwsCognito: $ref: '#/components/schemas/ProviderAwsCognito' - type: object required: - GenericOidc properties: GenericOidc: $ref: '#/components/schemas/ProviderGenericOidc' 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' 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. TenantId: type: string format: uuid ApiKeyId: type: string format: uuid description: API key identifier. MonitorStatus: type: string enum: - InitialUnhealthy - Unhealthy - Healthy 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' nullable: true 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 description: List of unstable features that are enabled. nullable: true update_info: allOf: - $ref: '#/components/schemas/UpdateInformation' nullable: true version: type: string description: 'The version corresponding to the type of `edition`. Format is `x.y.z`.' 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 ClusterMonitorEventId: type: string format: uuid description: Cluster monitor event identifier. 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. ProviderAwsCognito: type: object required: - issuer - login_url - logout_url properties: issuer: type: string login_url: type: string logout_url: type: string 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).' ApiPermission: type: string description: Permission types for invoking API endpoints. enum: - Read - Write 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 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' NewApiKeyRequest: type: object description: Request to create a new API key. required: - name properties: name: type: string description: Key name. example: my-api-key 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 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 description: URL that navigates the user to extend / upgrade their license nullable: true is_trial: type: boolean description: Whether the license is a trial remind_schedule: $ref: '#/components/schemas/DisplaySchedule' remind_starting_at: type: string format: date-time description: Timestamp from which the user should be reminded of the license expiring soon nullable: true valid_until: type: string format: date-time description: Timestamp at which point the license expires nullable: true 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."