API Reference

Ironflow provides multiple ways to interact with the platform:

Interface	Use Case
REST API	HTTP endpoints for triggers, runs, and management
JavaScript SDK	Full-featured SDK for browser and Node.js
Go SDK	Native Go SDK for workers and clients
Python SDK	Experimental Python HTTP client (no worker runtime yet)
Configuration	Environment variables, defaults, and SDK configuration
Platform API	Multi-tenant platform management — users, keys, roles, tenants, audit

---

Quick Links

REST API

• POST /ironflow.v1.IronflowService/Emit - Emit an event
• POST /ironflow.v1.IronflowService/ListFunctions - List registered functions
• POST /ironflow.v1.IronflowService/GetFunction - Get function details
• POST /ironflow.v1.IronflowService/ListRuns - List runs
• POST /ironflow.v1.IronflowService/GetRun - Get run details
• POST /ironflow.v1.EntityStreamService/ListStreams - List all entity streams
• GET /api/v1/flow/emit-edges - List learned function→event causation edges (flow map)
• GET /api/v1/flow/webhooks - List inbound webhook sources, retained activity summaries, and durable source→event edges (flow map)
• POST /ironflow.v1.ProjectionService/PauseProjection - Pause projection
• POST /ironflow.v1.ProjectionService/ResumeProjection - Resume projection
• DELETE /api/v1/projections/{name} - Delete projection
• POST /ironflow.v1.EventSchemaService/RegisterSchema - Register event schema
• POST /ironflow.v1.EventSchemaService/ListSchemas - List event schemas
• GET /api/v1/events/names - List distinct event names with occurrence counts (facet for the event-type filter). Query params: source, since, until. Counts are computed over at most the newest 10,000 matching events, and at most 200 names are returned. truncated: true means one of those caps was exceeded; only the scan cap makes the counts a recency window rather than environment totals.
• POST /api/v1/config/{name} - Set config (full replacement)
• PATCH /api/v1/config/{name} - Patch config (shallow merge)
• GET /api/v1/config/{name} - Get config
• GET /api/v1/config - List configs
• POST /api/v1/kv/buckets - Create a KV bucket
• GET /api/v1/kv/buckets/{bucket}/keys/{key} - Get a KV entry
• PUT /api/v1/kv/buckets/{bucket}/keys/{key} - Set a KV entry
• DELETE /api/v1/kv/buckets/{bucket}/keys/{key} - Delete a KV entry
• POST /api/v1/secrets - Create a secret
• GET /api/v1/secrets - List secrets (metadata only)
• GET /api/v1/secrets/{name} - Get secret metadata
• PUT /api/v1/secrets/{name} - Update a secret
• DELETE /api/v1/secrets/{name} - Delete a secret

JavaScript SDK

Browser (real-time subscriptions, triggers):

import { ironflow } from "@ironflow/browser";

ironflow.configure({ serverUrl: "http://localhost:9123" });

// Subscribe to events
const sub = await ironflow.subscribe("events:order.*", {
  onEvent: (event) => console.log(event),
});

// Invoke a function
const run = await ironflow.invoke("process-order", { data: { orderId: "123" } });

Node.js (workers, serve handlers):

import { ironflow, serve, createWorker } from "@ironflow/node";

// Define a function
const processOrder = ironflow.createFunction(
  { id: "process-order", triggers: [{ event: "order.placed" }] },
  async ({ event, step }) => {
    const result = await step.run("process", async () => ({ processed: true }));
    return result;
  }
);

// Push mode (serverless)
export const POST = serve({ functions: [processOrder] });

// Pull mode (worker)
const worker = createWorker({ serverUrl: "http://localhost:9123", functions: [processOrder] });
await worker.start();

Go SDK

import "github.com/sahina/ironflow-go/ironflow"

// Define functions
var myFunction = ironflow.CreateFunction(...)

// Interact with server
client := ironflow.NewClient(ironflow.ClientConfig{})
client.Emit(ctx, "event.name", map[string]any{"data": "value"})

Platform API

• POST /api/v1/platform/auth/login — Platform authentication
• GET /api/v1/platform/users — List platform users
• GET /api/v1/platform/tenants — List tenants

---

Server Endpoints

The server runs on port 9123 by default and exposes:

Endpoint	Description
/	Dashboard UI
/api/v1/*	REST API
/ws	WebSocket subscriptions
/health	Liveness probe (database only)
/ready	Readiness probe (database + NATS)
/metrics	Prometheus metrics (when IRONFLOW_METRICS_ENABLED=true)
/ironflow.v1.IronflowService/*	ConnectRPC: functions, events, runs, scoped injection (PauseRun, InjectStepOutput, PatchStep)
/ironflow.v1.WorkerService/*	ConnectRPC: pull-mode worker bidirectional streaming
/ironflow.v1.EnvironmentService/*	ConnectRPC: environment administration (compatibility surface; the hand-written SDK environment methods stay REST-backed)
/ironflow.v1.EntityStreamService/*	ConnectRPC: entity stream event sourcing
/ironflow.v1.ProjectionService/*	ConnectRPC: projection management and queries
/ironflow.v1.PubSubService/*	ConnectRPC: pub/sub subscriptions and consumer groups
/ironflow.v1.QueryService/*	ConnectRPC: SQL queries
/ironflow.v1.EventSchemaService/*	ConnectRPC: event schema registry
/ironflow.v1.WebhookService/*	ConnectRPC: webhook source management
/ironflow.v1.AuditService/*	ConnectRPC: history inspection (audit trail) queries
/ironflow.v1.TimeTravelService/*	ConnectRPC: history navigation (time-travel debugging)
/ironflow.v1.AgentToolsService/*	ConnectRPC: agent tool registry (exposeMcp runtime, issue #595)

See Configuration for environment variables, defaults, and SDK configuration.