DEVELOPERS

Wire it in.
Read it out.

Serumon is an integration-heavy product and we treat that as a first-class engineering surface: documented REST and streaming APIs, OT connectors, webhooks, an edge SDK for custom equipment, and a full audit export.

READ THE DOCS TALK TO ENGINEERING

REST+ STREAMING

OPC-UAFIRST CLASS

WEBHOOKSEVENT-DRIVEN

SDKEDGE + CLOUD

quickstart.sh

# read live vessel state
curl -H "Authorization: Bearer $SERUMON_TOKEN" \
  https://api.serumon.com/v1/vessels/V-07/state

# subscribe to decision records
serumon stream decisions --vessel V-07 --since 1h

# export the audit trail for a batch
serumon audit export --batch B-24118 --format jsonl

200 OK  streaming 14 events/min

API SURFACE

What you can call

STATE API

Live and historical state for vessels, lines, batches and SKUs, including predictions with their confidence.

DECISION API

Every agent decision record: observation, prediction, proposal, envelope, approver and outcome.

CONTROL API

Submit and approve proposals programmatically, subject to the same envelopes and approvals as the console.

BATCH API

Batch metadata, formula version, lot genealogy and the assembled release evidence pack.

AUDIT API

Immutable event export in JSONL, filterable by batch, vessel, actor, model version or time range.

ADMIN API

Envelopes, roles, model versions and autonomy rungs — all versioned, all dual-approved.

CONNECTORS

What we speak on the plant floor

OPC-UA

Primary path to vessels, homogenisers, fillers and line controllers, with per-tag permission scoping.

MODBUS

For older equipment where OPC-UA is unavailable, with explicit register mapping documentation.

MES / BATCH

REST and file-drop integration with batch systems, keeping them as the system of record.

LIMS + HISTORIAN

Read paths for lab assays, stability studies and long-horizon process history.

EDGE SDK

For equipment we have never seen

Cosmetics plants are full of equipment that predates every protocol you would like it to speak. The edge SDK exists so an integrator can wrap an unusual homogeniser, a bespoke filler or a custom vision rig and present it to the runtime as a normal device.

You implement read, write and health. The runtime handles envelopes, audit, retries, safe-state and model delivery.

Device adapters in Python or Rust.
Declarative tag schema with units and limits.
Health and watchdog contract built in.
Envelope enforcement handled by the runtime, not your adapter.
Local test harness with recorded plant traces.

adapter.py

from serumon.edge import Adapter, tag

class HomogeniserX(Adapter):
    speed = tag("rpm", unit="rpm", rw="rw",
                min=0, max=3600, rate_limit=120)
    temp  = tag("jacket_c", unit="C", rw="r")

    def read(self):
        return {"rpm": self.dev.speed(),
                "jacket_c": self.dev.temp()}

    def write(self, k, v):   # envelope already checked
        return self.dev.set(k, v)

    def health(self):
        return self.dev.ping()

EVENTS

Webhooks worth subscribing to

batch.risk_changed

Predicted micro, stability or spec risk crossed a threshold for an in-progress batch.

shade.drift_detected

ΔE trend projects a breach of the hold threshold before end of batch.

proposal.pending

An agent proposal is waiting on human approval, with the reasoning attached.

action.executed

A control action was written, with envelope, approver and model version.

giveaway.regressed

Fill distribution moved against target on a covered line or head.

model.promoted

A model version was promoted, canaried or rolled back on a specific vessel class.

INTEGRATION PATH

From access to first decision

01
SURVEY
Tag discovery across vessels, fillers and inspection; identify what is readable, writable and trustworthy.
02
CONNECT
Configure connectors, map tags to the canonical schema, validate units, ranges and update rates.
03
REPLAY
Run agents against recorded history first. Bugs in tag mapping surface here, not on a live batch.
04
GO LIVE
Shadow on the live line, then recommend, with webhooks and audit export wired into your systems.

REFERENCE

Rate limits and conventions

Rate limits and conventions
ASPECT	VALUE	NOTE
Auth	Bearer token / mTLS	Per-integration credentials, per-vessel scoping
REST rate limit	600 req/min	Burst 1200; 429 with Retry-After
Streaming	Server-sent events	Resumable with last-event-id
Idempotency	Idempotency-Key header	Required on all writes
Versioning	URL major version	Breaking changes get a new major, 12-month overlap
Timestamps	RFC 3339 UTC	Plant local time carried separately
Units	Explicit per tag	No implicit unit conversion, ever

ENGINEERING PRINCIPLES

How the API behaves

IDEMPOTENTALL WRITES

VERSIONEDALL MODELS

EXPLICITALL UNITS

EXPORTABLEALL DATA

STACK

What Serumon is built on

The control plane is Go and NestJS, the model services are Python and FastAPI, and the plant-edge runtime is Rust and C++ because deterministic latency is not negotiable.

Storage is PostgreSQL with pgvector, TimescaleDB for telemetry and Redis for hot state. Everything ships through GitHub Actions, Terraform and ArgoCD, with OTA delivery to the edge.

Edge runtime: Rust / C++ on K3s, IGX and Jetson.
Services: Go, Python FastAPI, NestJS control plane.
Data: PostgreSQL + pgvector, TimescaleDB, Redis.
AI: PyTorch, NVIDIA Isaac, Metropolis, Holoscan, Cosmos, cuOpt, Omniverse, LangGraph.
Ops: GitHub Actions, Terraform, ArgoCD, Datadog, Grafana, OpenTelemetry, Langfuse.

RUNTIME FACTS

EDGE OS: LINUX / K3s
CONTROL LANG: RUST + C++
P95 DECISION: <150 ms
OFFLINE: FULL CONTROL
OTA: SIGNED + STAGED
TELEMETRY: OPENTELEMETRY

DEVELOPER FAQ

Integration questions

BUILD

Get sandbox access

Integrators and internal automation teams can get sandbox credentials and the adapter SDK before any commercial conversation happens.

REQUEST SANDBOX READ THE DOCS

Wire it in.Read it out.