Skip to main content
Version: 2.0.0 (Latest)

REST API Reference

This document is the operational REST API reference for padas-api: the embedded control plane on Axum + Rustls that fronts the same process as StreamRouter, WAL subscriber, tasks, and connectors. /api/v1/* is the runtime orchestration surface—not a thin CRUD façade. Calls perform runtime state mutation, stream runtime coordination, and runtime lifecycle control (start/stop/restart, pause/resume, produce/consume, query) against direct daemon handles in EmbeddedApiState. The API-driven execution model means HTTP verbs align with execution graph changes, persistence projection updates (streams.json, tasks.json, connectors.json), and immediate runtime reconciliation inside one runtime engine address space.

All paths assume [api].prefix /api/v1 in padas.toml. Deeper topology and WAL semantics: Configuration & Runtime Engine, Runtime configurations.

Base URL examples

  • TLS (default shipped posture): https://<host>:8999
  • Lab without TLS: http://127.0.0.1:8999

Authentication​

When [api.auth].enabled = true, Axum request pipeline protection applies service-account middleware to the authenticated router: Bearer enforcement is all-or-nothing for embedded routes—GET /api/v1/health, /status, /metrics, /query, and POST /api/v1/system/reload all require Authorization: Bearer <token>; there is no anonymous bypass.

Operational security tone:

ConcernRuntime behavior
Bearer materialRead token (and expires_at) from service-account.token JSON at [api.auth].service_account_token_file.
Service-account token lifecycleGET /api/v1/auth/token/status inspects metadata; POST /api/v1/auth/token/refresh rotates with grace fields (old_token_valid_until, new_token_expires_at, …). Automation and UI/Core trust boundary: UI stores the same secret per Core row—rotation must update both sides or you enter 401 loops (Security).
Lockout semanticsRepeated failures increment per-client IP (from X-Forwarded-For / X-Real-IP); exceeding limits blocks the IP for lockout_duration_secs even for otherwise valid tokens until the window clears.
Token rotation expectationsDuring grace, old and new tokens may both work; after grace, stale automation tokens fail 401 until refreshed.
Auth-disabled lab risks[api.auth].enabled = false exposes the full runtime orchestration surface without credentials—lab-only on 127.0.0.1 or isolated network (Security).

When [api.auth].enabled = false, omit the header (lab only).

Failed auth returns 401 JSON with structured error / message fields.

Endpoints (embedded router)​

Replace {id} with the resource identifier. Query parameters are case-sensitive.

MethodPathRuntime & orchestration semantics
GET/api/v1/healthLiveness probe; still Bearer-gated when auth is on—use for orchestrator checks, not “anonymous up”.
GET/api/v1/statusRuntime diagnostics snapshot: service metadata, resources (streams/tasks/connectors), embedded metrics subset—runtime topology in one JSON tree (Glossary → Runtime status).
GET/api/v1/metricsPrometheus text from _padas_metrics contract; scrape interval drives runtime observability load (Monitoring).
POST/api/v1/system/reloadRuntime mutation of supported padas.toml keys; validate_only avoids applying—reload safety for ops (Configuration & Runtime Engine).
GET/api/v1/auth/token/statusToken lifecycle introspection for runbooks.
POST/api/v1/auth/token/refreshService authentication rotation; coordinate with UI account_token updates.
POST/api/v1/streamsExecution graph mutation: creates stream transport + registry row → streams.json persistence projection.
GET/api/v1/streamsList persisted streams.
GET/api/v1/streams/{id}Declarative config + overlays as stored.
PUT/api/v1/streams/{id}Runtime reconciliation: buffer/WAL/partition changes applied to live StreamRouter where supported.
DELETE/api/v1/streams/{id}Teardown runtime lifecycle for stream (force where implemented); persistence implications on dependents.
POST/api/v1/streams/{id}/pauseState transition: stop routing; buffers/WAL policy dependent.
POST/api/v1/streams/{id}/resumeResume runtime coordination on router path.
POST/api/v1/streams/{id}/restartEmbedded orchestration: bounce stream-side components without full process restart.
GET/api/v1/streams/{id}/statusStream-scoped runtime diagnostics (lag, errors, mode).
POST/api/v1/streams/{id}/dataProduce: append events—runtime backpressure / buffer mode applies.
GET/api/v1/streams/{id}/dataConsume / replay window via position, offset, limit, duration, timestamp_format—offset management visibility.
POST/api/v1/tasksNew execution unit + tasks.json; does not auto-start runtime execution until /start.
GET/api/v1/tasks / /{id}Declarative task definitions.
PUT/api/v1/tasks/{id}Update PDL/mode/sinks—may require restart for full execution scheduling pick-up.
DELETE/api/v1/tasks/{id}Stop + remove runtime lifecycle ownership.
POST/api/v1/tasks/{id}/startBegin PDL execution and subscriptions—task saturation risk if many tasks start together.
POST/api/v1/tasks/{id}/stopRuntime lifecycle halt; aggregation/window runtime state behaviour per config.
POST/api/v1/tasks/{id}/restartRuntime orchestration bounce for code/config pick-up.
GET/api/v1/tasks/{id}/statusRuntime diagnostics (timings, last_error, mode).
POST/api/v1/connectorsIngress/egress boundary definition + connectors.json.
GET/api/v1/connectorsList connectors (registry projection).
GET/api/v1/connectors/{id}Get connector definition.
PUT/api/v1/connectors/{id}Config mutation—often needs restart for connector IO loops to pick up.
DELETE/api/v1/connectors/{id}Remove connector runtime lifecycle registration.
POST/api/v1/connectors/{id}/startOpen sockets/files/protocol runtime coordination.
POST/api/v1/connectors/{id}/stopRelease external resources; backpressure visibility to upstream may change.
POST/api/v1/connectors/{id}/restartConnector stalls recovery runbook entry point.
GET/api/v1/connectors/{id}/statusConnector runtime diagnostics.
POST/api/v1/queryAd hoc historical reads / stream replay through query engine—WAL dependency (see Query execution behavior).
POST/api/v1/query/streamStreaming query / SSE-style path—replay latency sensitive.
POST/api/v1/query/testCapture validation / offline PDL against sample JSON—ties to Testing workflows without mutating runtime topology.

Content-Type: application/json for bodies unless connector-specific docs state otherwise.

Runtime execution model​

StageRuntime behavior
ProducePOST …/streams/{id}/data appends into StreamRouter buffers; WAL persist path runs if stream WAL enabled.
RouteVirtual shards / partitions map events through the execution graph toward subscribers.
Buffer[core.stream.buffer] modes define runtime backpressure (timeout / drop / block) before downstream visibility.
WAL persistWAL subscriber segments under [core.wal].path for runtime durability and hybrid consumer reads.
SubscribeTasks and consumers attach with offset management—lag thresholds flip readers toward WAL.
ExecuteTasks run PDL as execution units; aggregation holds runtime state until watermark/cleanup.
EmitOutputs route to sink streams or connector sinks—sink delivery semantics are class-dependent.
ConsumeGET …/data and query paths consume / replay with explicit position/offset/duration—replay latency grows with WAL depth and disk.

Runtime orchestration semantics​

OperationRuntime implication
Create (stream/task/connector)Extends execution graph; persists streams.json / tasks.json / connectors.json; live objects created on start or immediately per resource rules.
UpdateRuntime mutation + disk projection; may require restart for full pick-up—check handler responses and Configuration & Runtime Engine reload matrix.
DeleteRuntime lifecycle teardown and file row removal; dependents may fail until graph repaired—runtime drift if clients cache old IDs.
Pause (stream)State transition stopping routing while retaining definition—producers may block or drop per buffer mode.
Restart (stream/task/connector)Embedded orchestration bounce; expect brief metrics gaps and offset advancement depending on consumer.
ReloadPOST /api/v1/system/reload: TOML subset apply—runtime reconciliation vs process restart for unsupported keys.
QueryRead-heavy runtime execution on historical/replay path—does not substitute for task-defined continuous processing unless architected that way.
Replayposition/offset on GET …/data and query bodies—offset continuity requires WAL retention alignment.
ConsumePull model for operators and automation—stalled consumers show as empty reads until data arrives or WAL catches up.

Runtime drift: manual edits to registry JSON while Core is running can disagree with EmbeddedApiState—prefer API or controlled restarts (Configuration & Runtime Engine).

Runtime state and persistence​

LayerRole
Registry persistencestreams.json, tasks.json, connectors.json under [api.persistence].config_dir—authoritative persistence projection for API-managed objects.
Runtime stateIn-memory routers, buffers, connector handles, aggregation windows—lost on crash unless rebuilt from WAL + config.
WAL durabilitySegment files for stream transport history per policy—runtime recovery for lagging subscribers and query paths.
Runtime reconciliationStartup and post-reload paths reload registry + merge padas.toml / padas.default.toml into live services.
Reload behaviorsystem/reload applies validated subsets; mismatched expectations cause reload failures JSON—fall back to coordinated restart.
Offset continuityConsumers depend on persisted offsets + WAL retention; trimming retention too aggressively breaks replay after outages.

Query execution behavior​

POST /api/v1/query (and streaming query variants) execute PDL against a named stream with optional position / offset, limit, duration, timestamp_format. Execution is runtime execution on the daemon: it is not an isolated OLAP warehouse—query isolation is “separate read path,” not a separate process.

TopicBehavior
WAL dependencyHistorical path expects WAL-backed reads for the stream; if WAL is disabled, API returns 400 with WAL-unavailable semantics—operators must enable stream WAL or use live consume paths only.
Stream replayposition=earliest, latest, or offset=n drive stream offset semantics; combine with duration for bounded windows.
Historical readsScan cost scales with segment count and replay latency—watch disk and CPU during incident investigations.
Timestamp handlingtimestamp_format query param normalizes event time fields for clients—keep consistent across Monitoring scrapes and ad hoc query for comparable timelines.

For live stream inspection and troubleshooting loops, pair /query with /streams/{id}/status and /metrics (Monitoring, Troubleshooting & Logs).

curl examples​

Set shell helpers:

CORE=https://core.example.com:8999
TOKEN='<paste token JSON field>'
HDR=( -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" )

Self-signed TLS:

CURL_TLS=( --tlsv1.2 --cacert /path/to/ca.pem )
# or lab-only: CURL_TLS=( -k )

Status and health​

Why: validate TLS + Bearer + routing before wider automation. 200 JSON with resources means embedded control plane can read runtime topology; mismatch with UI usually means wrong token, TLS trust, or network partition—not “empty data”.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/status" | jq .
curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/health" | jq .

Metrics​

Why: confirm _padas_metrics exposition matches scrape config. 200 text beginning with # HELP / # TYPE indicates Prometheus handler healthy; empty or truncated responses suggest scrape timeout or metrics gaps during overload.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/metrics" | head

Token rotation​

Why: exercise service-account token lifecycle before automation cutover. Response JSON should include new token material and grace timestamps—update service-account.token consumers and UI account_token in one change window to avoid 401 loops.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/auth/token/refresh" | jq .

Stream lifecycle​

Why: prove produce path and StreamRouter acceptance before wiring tasks. POST /streams returning 201/200 with id confirms persistence projection write; …/status shows runtime lifecycle; …/data POST validates ingress.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/streams" \
  -d '{"stream":{"id":"ingest_http","partitions":1}}' | jq .

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/streams/ingest_http/status" | jq .

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/streams/ingest_http/data" \
  -d '{"msg":"probe"}' | jq .

Consume (position-based)​

Why: validate offset management and consumer lag behaviour. API enforces mutually consistent position / offset / limit / duration—400 text explains invalid combos.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" \
  "${CORE}/api/v1/streams/ingest_http/data?position=latest&limit=50&duration=2" | jq .

Task control​

Why: move an execution unit from defined → runtime execution. /start returning error JSON often means bad PDL, missing source stream, or saturated workers—check …/status and logs.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/tasks" \
  -d @task.json | jq .

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/tasks/my-task/start" | jq .
curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/tasks/my-task/status" | jq .

Connector control​

Why: confirm connector IO loops for syslog/http/etc. /start without prior streams readiness yields connector stalls or task errors—order operations: streams → tasks → connectors as per topology.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/connectors/syslog-in/start" | jq .
curl "${CURL_TLS[@]}" -sS "${HDR[@]}" "${CORE}/api/v1/connectors/syslog-in/status" | jq .

Query​

Why: runtime diagnostics and query replay for incident timelines. 400 WAL unavailable confirms stream WAL disabled—align with Query execution behavior. 200 with result rows validates PDL + historical reads path.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST \
  "${CORE}/api/v1/query?timestamp_format=epoch_ms" \
  -d '{"stream":"ingest_http","query":"SELECT * FROM stream LIMIT 10","position":"latest"}' | jq .

Configuration reload​

Why: safe runtime mutation of supported TOML without full restart. Start with validate_only to catch unsupported keys—reload failures return structured errors; do not assume silent no-ops.

curl "${CURL_TLS[@]}" -sS "${HDR[@]}" -X POST "${CORE}/api/v1/system/reload" \
  -d '{"validate_only":true}' | jq .

Runtime services behind the API​

Handlers attach to EmbeddedApiState: no subprocess orchestration—each request mutates or reads direct daemon handles inside the runtime engine. Implications:

  • Runtime coordination is synchronous with the Axum worker unless handlers spawn internal tasks—latency implications for large JSON payloads and synchronous WAL reads.
  • Crash semantics: panics surface as 500; there is no external supervisor restarting a “worker child” per request.
  • Shared runtime ownership streams, tasks, and connectors share CPU, disk, and scheduler interaction—task saturation or WAL IO spikes affect /metrics and /query on the same host.
  • Backpressure visibility surfaces as HTTP errors, dropped events (per buffer mode), or lag fields on …/status—not as a separate queue depth API unless exposed in diagnostics JSON.

Streams, tasks, connectors — REST vs runtime​

ConceptREST / persistence projectionRuntime engine ownership
StreamCRUD + pause/resume/restart; streams.json row.StreamRouter buffers, optional WAL subscriber, offset management, cleanup timers—stream transport hot path.
TaskCRUD + start/stop/restart; tasks.json + execution overlays.Execution scheduling, PDL evaluation, aggregation runtime state, sink emission—execution unit.
ConnectorCRUD + lifecycle; connectors.json.Connector IO loops, protocol parsers, sink/source runtime backpressure—ingress/egress boundaries.

State reconciliation: REST writes update JSON then apply to in-memory graph—transient failures can leave “saved but not running” unless …/status is green. WAL interactions: stream WAL toggles affect whether consume / query can replay. Runtime scheduling: start order matters when tasks depend on streams and connectors on tasks.

Deployment and runtime synchronization​

  • Bootstrap: provision padas.toml, Rustls PEMs, writable core.data_dir, and [api.persistence].config_dir before systemd/container start (package as a service per your OS—see Runtime configurations).
  • UI/Core synchronization: copy service-account.token field into Cores; verify GET /api/v1/status from the same network path the UI server uses—UI rows do not replace on-disk padas.toml.
  • Rolling deploy implications: one replica restart drops runtime state for that process—expect replay lag, brief metrics gaps, and connector stalls during redelivery windows.
  • API-driven orchestration: prefer idempotent automation sequences (define → start → …/status poll) rather than blind parallel /start storms.
  • Reload safety: POST /api/v1/system/reload with validate_only first; unsupported keys require restart coordination with upstream pause/drain.
  • State recovery expectations: after crash, runtime reconciliation reloads registry + WAL policy—validate offset continuity and WAL retention cover your RPO for query replay.

Runtime troubleshooting checkpoints​

SymptomFirst checks
401 loopsToken rotation grace expired; automation still on old Bearer; lockout from bad scripts hammering auth.
Reload failuressystem/reload JSON error text; key not supported—plan process restart.
WAL unavailableStream WAL disabled—query / hybrid consume paths return 400.
Stalled consumers…/streams/{id}/status, lag thresholds, sink health.
Offset driftMixed position/offset usage across clients; retention trimmed mid-outage.
Stream backpressureBuffer mode, produce 429/errors, router diagnostics.
Connector stalls…/connectors/{id}/status, external dependency timeouts, restart path.
Task saturation…/tasks/{id}/status, worker caps, PDL cost.
Metrics gapsScrape timeout vs Core overload; _padas_metrics level too low/high.
Replay lagWAL segment count, disk IO, duration too large on hot streams.

More playbooks: Troubleshooting & Logs → REST API and Core runtime.

Operational troubleshooting​

See Troubleshooting & Logs → REST API and Core runtime for troubleshooting loops tying query replay, capture validation (Testing), and live stream inspection together.