Skip to main content
Filament’s API is ConnectRPC, generated from the protobuf definitions in protos/ingestion/v1/ and protos/metrics/v1/. ingestion.v1.IngestionService (connectors, connections, pipelines, runs) and metrics.v1.MetricsService (dashboard aggregations) share one listener. The built-in web app uses this same API; there is no separate internal API behind it. Every RPC is an HTTP POST to /{package.Service}/{Method}:
The server binary serves both services on SERVER_ADDR (default :8080). The standalone binary and the embeddable app.Run library serve the same API on INGESTION_ADDR (default :8080).

​
Protocols

The servers listen for HTTP/1.1 in plaintext. That determines which of the three ConnectRPC wire protocols work against a default deployment. Plain gRPC needs HTTP/2 end to end. The shipped binaries listen plaintext without h2c, so a stock gRPC client fails against them directly. If you need plain gRPC, terminate TLS with HTTP/2 at a proxy or load balancer in front of the server. Connect and gRPC-Web clients need nothing extra. The Connect protocol is ordinary JSON over POST, so any HTTP client works:

​
Authentication

There is none. The API ships with no authentication, no interceptors, and CORS open to any origin. Anyone who can reach the listener can read and write everything. Run Filament on a private network and control access at the network layer, whether through a VPN, a service mesh, or an authenticating reverse proxy in front of the port.

​
Tenancy

Every request message carries a tenant_id. An empty string resolves to the default tenant, the zero UUID 00000000-0000-0000-0000-000000000000, which the server creates at startup. Single-tenant deployments can omit the field everywhere and never think about it.

​
Errors

Failures are standard Connect error codes. These are the codes you will actually see. Some specifics worth knowing:
  • invalid_argument covers missing required fields, an invalid graph on CreatePipelineVersion, a bad cron expression, and an undecodable pagination cursor.
  • failed_precondition covers deleting a connection a pipeline still references, updating a deleted connection, a secret that fails to resolve, and TailRun without an event bus.
  • aborted means the version on an update no longer matches the stored row. Re-read and retry.
  • unimplemented covers MetricsService without a metrics store and discovery or column RPCs on connectors that don’t support them.
Validation of connector configs is the exception. ValidateConfig and ValidatePipeline return validation problems in their response bodies rather than as RPC errors, so a form can display every failure together.

​
Pagination

List RPCs take an optional PaginationRequest. The response’s PaginationResponse carries total plus previous_cursor and next_cursor when more pages exist in that direction. Omitting pagination entirely returns every row, which is convenient for scripts but expensive on large tables.

​
Health

Three plain HTTP endpoints sit beside the RPC routes on the same listener:
  • GET /livez: always 200 while the process is up
  • GET /startupz: 200 once dependencies are connected and modules are mounted
  • GET /readyz: 200 after startup while Postgres and NATS/JetStream answer; the server also ensures the default tenant exists
The control plane serves the same endpoints on HEALTH_ADDR (default :8081).

​
API areas

Connectors

The catalog of registered sources and sinks, with config validation and resource discovery.

Connections

Reusable, tenant-scoped sources and sinks with managed secrets.

Pipelines

Mutable metadata over immutable graph versions, plus schedules.

Runs

Compiling, listing, and live-tailing pipeline executions.

Metrics

The read-only aggregation service behind the dashboard.