SlimFaas API Reference

This inventory describes the routes registered by the SlimFaas runtime in this checkout. Use the Guided Tour for executable cURL examples and the Bruno collection for ordered requests with assertions.

Addresses and response conventions

Use http://127.0.0.1:30020 for the native-local entrypoint, or http://127.0.0.1:30021 for the tutorial's Kubernetes port-forward and Docker Compose. WebSockets use /ws on the entrypoint in native local mode and a dedicated port, 5003 by default, in the other orchestrators.

HTTP function, event, job and dashboard endpoints check the configured SlimFaas ports. Visibility and trust are evaluated by the relevant endpoint; there is no universal bearer-token authentication scheme supplied by these routes. Private functions return 404 to untrusted callers. Callers are classified by their connection address; X-Forwarded-For is honoured only from the proxies declared in SlimFaas:TrustedProxies (see Functions). Native local mode shares the host network.

JSON property names below preserve the server's casing. In particular, generated data IDs are JSON strings for sets/hashsets, plain text for files, and {"Id":"..."} for jobs/schedules. A 202 means acceptance, not completion. CPU load shedding can produce 429 with Retry-After; storage capacity or availability can also produce 429, 413 or 503 on data/queue paths.

Dashboard, health and wake-up

See tour steps 1–2.

The health middleware matches paths without restricting the HTTP method; use GET for probes. SSE event names are state, activity and activity_batch. state includes functions, jobs, queue lengths, nodes and front status. Keep connections open or impose a deliberate timeout when exploring with cURL. See UI configuration.

Function calls and callbacks

See synchronous calls and async calls.

The wildcard represents the application's path; it is not a literal part of the URL. The registered HTTP methods do not guarantee that the downstream application supports them. For example, the demo exposes GET /hello/{name} and POST /fibonacci; calling an unsupported application method can return 405.

An async worker sends SlimFaas-Element-Id to the function. If the function returns 202, it must later call the completion route with that ID. success (case-insensitive) maps to successful completion; other nonempty status strings map to failure. Use the documented success or error values. The callback does not publish a queryable result resource. See Functions for headers, retry configuration and idempotency.

Events

See publishing an event.

HTTP delivery targets ready replicas. Sleeping replicas are skipped and the publication does not wake or durably queue work for them. A configured subscriber can exist while having no ready replicas, so 204 alone does not establish delivery. Per-target send failures are logged; the publisher does not receive each function's result. Connected WebSocket subscribers are handled through the WebSocket transport. See Events.

Jobs and schedules

See jobs in the tour.

Creation/deletion validate a configuration name of 3–30 lowercase letters, digits, underscores or hyphens (names are normalized to lowercase). Configuration visibility and image allowlists govern which jobs callers may request. Optional job fields include image, environment, dependencies, resources, restart policy, backoff and retention; see the full Jobs reference. Schedule endpoints return 404 if the schedule service is unavailable. Capture the returned ID; a completed execution may disappear before a subsequent deletion.

Reading after a write

The entrypoint can route consecutive requests to different nodes. On a newly started cluster, a follower can briefly return 404 for a just-created ID, or still show a just-deleted value. Retry the read with a deadline; do not blindly repeat writes, increments or job submissions. The terminal smoke test and Bruno read assertions allow up to ten seconds for visibility. Bruno keeps the original HTTP response visible while its assertion polls for the expected state. Persistent 404 responses still require checking the ID, TTL and access configuration.

Data sets and counters

See data exercises and Data Sets.

IDs must contain 1–200 letters, digits, ., _ or -. Bodies are limited to 1 MiB (413 on overflow). Invalid IDs/parameters return 400. TTL is milliseconds; numeric mutations accept an optional positive ttl, otherwise preserve the existing expiration. Missing or expired counters start at zero. Invalid stored numeric contents and overflow return 409 without changing the value.

Sets and files use Data:DefaultVisibility (Data__DefaultVisibility in the environment), which defaults to Private. An untrusted caller receives 404. The tutorial explicitly uses public access for these APIs.

Hashsets

The HTTP facade stores the body in one value field. It is not an arbitrary hash-field manipulation API. The same ID and 1 MiB body constraints apply. The current hashset route registrations do not attach DataVisibilityEndpointFilter; Data__DefaultVisibility does not control this route family. Review exposure at your gateway. The tour demonstrates create/read/list/delete.

Files

Set Content-Type and optionally Content-Disposition when uploading. Send the raw file, not a multipart envelope. cURL --data-binary @file sends its length. Invalid/reserved IDs are rejected; downloads of reserved internal IDs return 404. The Files guide explains disk storage, peer retrieval, upload concurrency limits and the distinction between temporary artifacts and durable application storage.

Metrics and diagnostics

See tour diagnostics and Autoscaling.

/debug/promql/eval registers referenced metrics for scraping. A query over a new series may need samples before it returns a finite result. The scaling playground only reads collected observations and does not register metrics. These are diagnostic routes and do not apply the data or function visibility policies.

WebSocket transport

GET /ws upgrades an HTTP connection to WebSocket. A non-upgrade request returns 400; on the wrong configured port it returns 404. Native local mode shares the entrypoint; Kubernetes exposes service port 5003. The basic Compose tour does not publish that dedicated port.

Clients register function configuration, receive sync/async/event messages, and send response frames or acknowledgments. HTTP requests to virtual functions still use the normal function routes. Use the official .NET and Python clients, which implement registration and streaming. This protocol is kept in the collection's Manual reference rather than treated as a finite HTTP test.

Internal interfaces

These routes are documented for architecture and operations. They are not introductory API calls and are excluded from the automated tour.

Raft consensus additionally uses DotNext's protocol handler on the internal listener. /SlimData/ListLength appears in redirect configuration but is not registered as an application handler; do not treat it as a supported public command. Keep SlimData listeners private to the cluster. The native supervisor binds loopback and requires its per-session token header; let slimfaas local manage it.

Application routes versus SlimFaas routes

/hello, /fibonacci, /download, /error, /compute and /computeWithCallback belong to the Fibonacci demo. They become accessible through /function/{name}/... or /async-function/{name}/.... Kafka producer /send/{value} similarly belongs to an optional example application. These are examples of forwarding, not additional SlimFaas API route families.

Scaling simulation request

curl -X POST http://localhost:30020/debug/scaling/simulate \
  -H 'Content-Type: application/json' \
  -d '{"Function":"worker","CurrentReplicas":0,"ScaleFromZero":true,"Triggers":[{"Index":0,"Query":"sum(jobs_pending)","Source":"jobs","MetricType":"AverageValue","Threshold":20,"Value":73}]}'

Function is required. Optional overrides are CurrentReplicas, ReplicaMax, ClearReplicaMax, ScaleFromZero, Behavior and Triggers. Each trigger override identifies a configured zero-based Index and supplies Query, Source (null for the historical scope), MetricType, Threshold and optional Value. Omitting/null Value uses collected observations. ClearReplicaMax: true removes the maximum only in the preview; it cannot accompany a numeric ReplicaMax. Source definitions and URLs are never accepted as overrides.

The 200 response contains CapturedAtMs, Current, Simulated and Limitations. Each decision includes raw/policy/stabilized/final targets, reasons, source/trigger states and the frozen activity/dependency context. Preview application status is Preview; no orchestrator request is sent. Invalid input returns 400, disabled front/disallowed ports/unknown function 404, an oversized request 413, non-JSON content 415, exhausted simulation slots 429, and leader/data-budget unavailability 503.

The scaling SSE emits scaling_state with Session, Status, ServerTimeMs, Function, Decision, Configuration, observed requested/ready counts, Events, Truncated and RefreshIntervalMs. The first frame includes retained history; subsequent frames include only newer events. Event IDs are ordered within a session. Reset the client history when Session changes. A scaling_error event terminates a started stream on leader failure so the client can reconnect. Public SSE failures before the first frame use the corresponding HTTP status; exhausted viewer slots return 429.

/internal/scaling/state and /internal/scaling/simulate are leader-only peer routes, additionally restricted to direct SlimFaas member connections matched by IP. They do not forward recursively. See the UI guide for retention, limits and deployment behavior.