FoundryNet, Developer Docs & API Reference

API Reference

All /v1/* requests need Authorization: Bearer fnet_… and (where applicable) Content-Type: application/json. Base URL: https://forge.foundrynet.io.

Quick start

Get a free key instantly, no email gate: forge.foundrynet.io/pricing (Sandbox: 3 machines, no card)
Identify a machine: POST /v1/identify
Send data: POST /v1/normalize
Connect a tool: POST /v1/tools
Set up automation: POST /v1/triggers/natural
Query history: GET /v1/history/{machine_id}
Cryptographic verification: POST /v1/settle

Endpoints

POST /v1/identify

Provision or look up a persistent, cryptographically verified identity (machine_id) for one machine. Idempotent on (oem, model, serial).

{
  "oem":    "fanuc",
  "model":  "Robodrill α-D21MiB5",
  "serial": "R30iB-12345",
  "site":   "Line 3"
}

{
  "machine_id":     "mach_4de03b",
  "internal_id": "fanuc:robodrill-a-d21mib5:r30ib-12345",
  "created":     true,
  "machine":     { "status": "active" },
  "first_seen":  "2026-05-04T01:00:00Z"
}

POST /v1/normalize

Translate raw OEM telemetry to canonical FCS data. Auto-provisions identity from oem/model/serial when no machine_id is given. Returns triggers_fired[] when any active trigger matches. Optional idempotency_key dedups retries within 24h. Optional observed_at (ISO 8601 controller clock) is stored alongside the server ingested_at.

{
  "data":   { "Spindle_Speed": 2200, "spindle_load": 92 },
  "oem":    "fanuc",
  "model":  "Robodrill α-D21MiB5",
  "serial": "R30iB-12345",
  "observed_at":     "2026-05-05T09:30:15Z",
  "idempotency_key": "optional-caller-supplied-key"
}

{
  "normalized":      { "spindle_speed_rpm": 2200, "spindle_load_pct": 92 },
  "field_mappings":  { "spindle_load": { "mapping_id": "6c34…", "canonical": "spindle_load_pct", "confidence": 0.93 } },
  "fields_total":    2, "fields_renamed":  2, "fields_identity": 0, "fields_unknown":  0,
  "coverage_pct":    100,
  "machine_id":      "mach_4de03b",
  "history_id":      "c419…",
  "triggers_fired":  [{ "trigger_id": "7f0c…", "trigger_name": "high spindle load", "actual_value": 92 }]
}

POST /v1/tools

Register a webhook endpoint as a tool. Triggers reference these by tool_id. auth_secret returned ONCE on create; never read back via GET.

{
  "name": "slack-maintenance",
  "url":  "https://hooks.slack.com/services/T…/B…/xxx",
  "method": "POST",
  "payload_template": { "text": "Alert: {{oem}} {{model}}, {{field}} at {{value}}" },
  "auth_type": "none"
}

{ "id": "add2…", "name": "slack-maintenance", "auth_type": "none", "enabled": true }

POST /v1/triggers/natural

Parse a natural-language instruction into a structured trigger. NEVER auto-activates; returns parsed_trigger for review and explicit POST to /v1/triggers.

{ "machine_id": "mach_4de03b", "instruction": "Alert maintenance Slack when spindle load exceeds 90." }

{
  "parsed_trigger": {
    "machine_id": "mach_4de03b",
    "name": "Spindle Load Alert",
    "condition": { "field": "spindle_load_pct", "op": ">", "value": 90 },
    "actions":   [{ "tool_id": "add2…" }]
  },
  "confirmation_required": true
}

GET /v1/history/{machine_id}

Per-machine canonical history. Query params: from, to (ISO-8601), fields (csv), limit (≤1000), summary (bool).

GET /v1/history/mach_4de03b?limit=5&summary=true

{
  "machine_id":  "mach_4de03b",
  "machine":  { "oem": "fanuc", "model": "Robodrill α-D21MiB5", "site": "Line 3" },
  "row_count": 2,
  "avg_coverage": 100,
  "fields_covered": ["spindle_load_pct", "spindle_speed_rpm", "sensor_readings.coolant_temp"]
}

POST /v1/settle

Create a tamper-evident, independently auditable record. Add ?batch=true with body {"machine_id": "…"} to hash and roll up all unsettled events for that machine into one verifiable record.

POST /v1/settle?batch=true
{ "machine_id": "mach_4de03b" }

{
  "machine_id":      "mach_4de03b",
  "verification_hash":  "413d5ec…",
  "event_count":  4,
  "record_ref": "2yiyp…",
  "verify_url":   "https://forge.foundrynet.io/v1/verify/2yiyp…"
}

MCP server

MCP endpoint (streamable HTTP): https://mcp.foundrynet.io/mcp

Forge exposes 30 MCP tools over mcp.foundrynet.io/mcp, spanning normalization, prediction, operations analytics, and governance. GET https://mcp.foundrynet.io/health and GET https://forge.foundrynet.io/health both report 30. They work across 14 industrial protocols and 18 OEM families.

Cloud prediction tools

predict_breach: TimesFM forecast of when a machine exceeds a threshold, with confidence intervals
remaining_life: remaining useful life estimate for a machine
fleet_health: score an entire operation in one call
predict_batch: batch fleet prediction across many machines
detect_anomalies: surface out-of-distribution telemetry
machine_intelligence: complete machine intelligence in one call

Cloud core tools

identify_machine: provision/lookup machine_id from (oem, model, serial)
normalize_telemetry: raw OEM data → canonical FCS, with auto-provision + trigger eval
query_machine_history: time-series + summary over canonical_data
create_automation: natural language → parsed_trigger (review-then-activate)
activate_automation: arm a parsed_trigger after user confirmation
list_automations: show all triggers configured for a machine
disable_automation: pause a trigger without deleting it (reversible)
delete_automation: soft delete (30-day restorable); ?permanent=true for hard delete
restore_automation: undo a soft delete within 30 days
query_webhook_history: HTTP status, retry counts, latency for a trigger's deliveries
verify_on_chain: create a tamper-evident record (single payload OR batched)

Reliability + record integrity

Soft delete

DELETE /v1/triggers/{id} defaults to soft delete, sets deleted_at, hides from list/eval, restorable for 30 days via PATCH /v1/triggers/{id}/restore. Add ?permanent=true for irrecoverable hard delete.

Idempotency

/v1/normalize accepts an optional idempotency_key. If absent, server synthesizes sha256(machine_id + canonical(data))[:32]. Repeats within 24h return the original response with deduplicated: true and skip trigger evaluation.

Coverage metric

Every /v1/normalize response carries three counters: fields_renamed (source != canonical), fields_identity (source == canonical), fields_unknown (no mapping). coverage_pct = (renamed + identity) / total.

Record timestamps

observed_at (ISO 8601 from the controller clock) is optional on /v1/normalize. Stored alongside ingested_at (server). When the difference exceeds 60s, response includes clock_skew_warning. Sustained-condition windows reference observed_at when present.

Structured errors

{
  "error":  true,
  "status": 422,
  "field":  "body.oem",
  "reason": "Field required",
  "received_value": {},
  "suggestion":     "e.g. 'fanuc'",
  "additional_errors": [ { "field": "body.model", "reason": "Field required" } ]
}

System requirements

The Forge kernel runs as a Docker container on any Linux host: cloud, on-premise server, industrial PC, or edge gateway.

Minimum (edge deployment)

CPU:      2 cores, x86_64 or ARM64
RAM:      4 GB
Storage:  10 GB available
OS:       Linux (Ubuntu 20.04+, Debian 11+, Amazon Linux 2)
Network:  Ethernet to OT network (for Modbus / OPC UA / SNMP / BACnet)
          Optional internet for cloud sync and updates
Runtime:  Docker 20.10+ or AWS Greengrass V2

Recommended (production)

CPU:      4 cores
RAM:      8 GB
Storage:  50 GB (accommodates extended telemetry history)
Network:  1 Gbps to OT network + internet for CMMS and updates

Cloud deployment

Any container host: Railway, AWS ECS, GCP Cloud Run, Azure Container Apps. No special hardware. Connects to equipment via API or protocol bridge.

Resource profile

Container image:    ~2.2 GB (compressed ~900 MB)
Runtime memory:     ~1.1 GB RSS steady state, ~1.5 GB peak
CPU at idle:        < 5% single core
CPU during predict: ~40% single core for 2-3 seconds
Bandwidth:          < 1 MB/hour per machine at 1 reading/second

What is in the 1.1 GB

Normalization engine (BGE-M3 embeddings):  ~600 MB
Prediction engine (TimesFM):                ~400 MB
Application + vertical packs + schema:      ~100 MB

Supported protocols

MQTT / Sparkplug B    (push, real-time streaming)
Modbus RTU / TCP      (poll, legacy PLCs and sensors)
OPC UA                (subscribe, modern controllers)
SNMP                  (poll, servers and network equipment)
BACnet/IP             (subscribe, building automation)
ROS2 / DDS            (subscribe, robotics and AMR fleets)
J1939 / CAN           (listen, vehicles and heavy equipment)
MAVLink               (listen, drones and aerial vehicles)
REST API              (push or pull, any HTTP-capable device)
CSV upload            (batch, historical data import)

No new hardware required

Forge connects to your existing sensors, PLCs, and controllers through the protocols they already speak. No proprietary gateways, no sensor replacements, no wiring changes.

Pricing

Monitoring machines? It's $49/machine/month, flat: unlimited streaming ingestion, normalization, and predictions. Start free (3 machines, no card) or go Production at forge.foundrynet.io/pricing.

The rates below are the pay-per-call option for developers and AI agents making occasional queries, not monitoring machines (that's the flat plan above). Query GET /v1/usage for live counts and an estimated bill.

POST /v1/normalize: 1¢ per call
Trigger fire (per webhook delivery, only on 2xx), 5¢
POST /v1/settle?batch=true: 2¢ per batch verified (skipped verifications are free)
GET /v1/history/{machine_id}: 1¢ per query
POST /v1/identify: free
POST /v1/triggers/natural: free (setup step; revenue comes from the trigger fires it produces)
POST /v1/feedback/{mapping_id}/...: free
Trigger evaluation (the eval pass during /v1/normalize), free; you only pay for fires that successfully deliver

Get a key instantly, no email gate: start free or go Production at forge.foundrynet.io/pricing. Site licenses for integrators: get in touch.

Developer docs