Internal site. Jolli authentication required to view.
Skip to Content
🛠️ SDKs and APIsRest Api Overview

Last Updated: 3/19/2026

REST API Overview

The Feldera REST API provides programmatic access to all platform functionality, including pipeline management, data ingestion, and query execution. The API follows REST principles and uses JSON for request and response bodies.

Base URL

The API is served at the base path /v0 on your Feldera instance. For example, if Feldera is running locally on port 8080:

http://localhost:8080/v0

All endpoint paths in this documentation are relative to this base URL.

Authentication

The Feldera API supports two authentication methods:

API Keys

API keys provide a simple way to authenticate programmatic access. Create an API key using the /v0/api_keys endpoint:

curl -X POST http://localhost:8080/v0/api_keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-api-key"}'

The response includes the generated API key, which you should store securely as it cannot be retrieved again:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-api-key",
  "api_key": "apikey:v5y5QNtlPNVMwkmNjKwFU8bbIu5lMge3yHbyddxAOdXlEo84SEoNn32DUhQaf1KLeI9aOOfnJjhQ1pYzMrU4wQXON6pm6BS7Zgzj46U2b8pwz1280vYBEtx41hiDBRP"
}

Use the API key in the Authorization header:

curl -H "Authorization: Bearer apikey:v5y5QNtlPNVMwkmNjKwFU8bbIu5lMge3yHbyddxAOdXlEo84SEoNn32DUhQaf1KLeI9aOOfnJjhQ1pYzMrU4wQXON6pm6BS7Zgzj46U2b8pwz1280vYBEtx41hiDBRP" \
  http://localhost:8080/v0/pipelines

JWT Tokens

When authentication is configured (AWS Cognito or Generic OIDC), you can use JWT tokens obtained through the OAuth2/OIDC login flow. Pass the JWT token in the Authorization header with the Bearer scheme.

Core Endpoints

Pipeline Management

Create a Pipeline

POST /v0/pipelines

Creates a new pipeline with the specified SQL program and configuration.

List Pipelines

GET /v0/pipelines

Returns all pipelines. Use the selector query parameter to control which fields are returned (all, status, or status_with_connectors).

Get Pipeline Details

GET /v0/pipelines/{pipeline_name}

Retrieves detailed information about a specific pipeline.

Update Pipeline

PUT /v0/pipelines/{pipeline_name}   # Full update
PATCH /v0/pipelines/{pipeline_name} # Partial update

Updates an existing pipeline. Pipelines can only be updated while stopped.

Delete Pipeline

DELETE /v0/pipelines/{pipeline_name}

Deletes a pipeline. The pipeline must be fully stopped before deletion.

Pipeline Lifecycle

Start Pipeline

POST /v0/pipelines/{pipeline_name}/start

Starts a pipeline. Use the initial query parameter to specify whether to start in running, paused, or standby mode.

Pause Pipeline

POST /v0/pipelines/{pipeline_name}/pause

Pauses a running pipeline. The pipeline continues to maintain state but stops processing input.

Resume Pipeline

POST /v0/pipelines/{pipeline_name}/resume

Resumes a paused pipeline.

Stop Pipeline

POST /v0/pipelines/{pipeline_name}/stop

Stops a pipeline. Use force=false (default) to checkpoint before stopping, or force=true to stop immediately.

Data Ingestion

Push Data to a Table

POST /v0/pipelines/{pipeline_name}/ingress/{table_name}?format={format}

Pushes data to an input table. Supported formats include json and csv. The format parameter specifies the data encoding.

Example:

curl -X POST "http://localhost:8080/v0/pipelines/my_pipeline/ingress/users?format=json" \
  -H "Content-Type: application/json" \
  -d '{"insert": {"id": 1, "name": "Alice"}}'

Query Results

Subscribe to View Updates

POST /v0/pipelines/{pipeline_name}/egress/{table_name}?format={format}

Subscribes to a stream of updates from a view or table. The pipeline continuously sends changes until the connection is closed.

Execute Ad-hoc Query

GET /v0/pipelines/{pipeline_name}/query?sql={sql}&format={format}

Executes an ad-hoc SQL SELECT query against the pipeline’s materialized views. Supported formats: text, json, parquet.

Example:

curl "http://localhost:8080/v0/pipelines/my_pipeline/query?sql=SELECT%20*%20FROM%20users&format=json"

Pipeline Statistics

Get Pipeline Stats

GET /v0/pipelines/{pipeline_name}/stats

Returns detailed statistics about a running or paused pipeline, including:

  • Input/output connector metrics
  • Records processed
  • Memory and storage usage
  • Error counts

Get Pipeline Metrics

GET /v0/pipelines/{pipeline_name}/metrics?format={format}

Returns metrics in Prometheus format (default) or JSON. Use this endpoint to integrate with monitoring systems.

Error Handling

The API uses standard HTTP status codes:

  • 2xx: Success
  • 400: Bad request (invalid parameters)
  • 401: Unauthorized (missing or invalid authentication)
  • 404: Resource not found
  • 409: Conflict (e.g., duplicate name)
  • 500: Internal server error
  • 503: Service unavailable (e.g., pipeline not ready)

Error responses include a JSON body with details:

{
  "message": "Human-readable explanation",
  "error_code": "CodeSpecifyingError",
  "details": {}
}

The error_code field provides a machine-readable error type (e.g., UnknownPipelineName, DuplicateName).

Pagination and Filtering

The /v0/pipelines endpoint supports the selector query parameter to control response size:

  • all: Returns all pipeline fields (default)
  • status: Returns only status-related fields
  • status_with_connectors: Returns status fields plus connector error statistics

Rate Limiting

The API does not currently impose rate limits, but clients should implement retry logic with exponential backoff for transient errors (408, 502, 503, 504).

OpenAPI Specification

The complete API specification is available in OpenAPI 3.0 format at /openapi.json. You can use this specification with tools like Swagger UI or to generate client libraries.

WebSocket Support

Some endpoints support WebSocket connections for streaming data:

  • /v0/pipelines/{pipeline_name}/query: Stream ad-hoc query results
  • /v0/pipelines/{pipeline_name}/egress/{table_name}: Stream view updates

Versioning

The API is currently at version v0. The version is included in the URL path to allow for future API evolution while maintaining backward compatibility.

What’s Next

  • Python Sdk: Use the Python SDK to interact with Feldera programmatically with a higher-level interface.
  • Ad Hoc Queries: Learn how to run ad-hoc SQL queries against your pipeline’s materialized views.
Python SdkMetrics Monitoring