API Reference

Ironflow provides multiple ways to interact with the platform:

Interface	Use Case
REST API	HTTP endpoints for management and operations, and the ConnectRPC calls that replaced the removed event, function and run routes
Push protocol	The HTTP contract between the engine and a push-mode function endpoint
JavaScript SDK	Full-featured SDK for browser and Node.js
Go SDK	Native Go SDK for workers and clients
Python SDK	Python REST and ConnectRPC clients, polling and streaming workers, and push serve (ASGI)
Configuration	Environment variables, defaults, and SDK configuration
Platform API	Multi-tenant platform management — users, keys, roles, tenants, audit

---

Quick Links

REST and ConnectRPC

• 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"})

Python SDK

Pull workers (ironflow.worker), push handlers (ironflow.serve), and the REST and ConnectRPC clients are covered in the Python SDK reference.

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 (not served with --headless)
/api/v1/*	REST API
/ws	WebSocket subscriptions
/health	Liveness probe (database only). Route traffic on it
/ready	Readiness probe (database, NATS and the engine streams). Do not route traffic on it
/metrics	Prometheus metrics (when IRONFLOW_METRICS_ENABLED=true; on the dedicated listener when spec.observability.metrics.port is set)
/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 and delivery log. Responses use snake_case field names, unlike the other services (ADR 0023)
/ironflow.v1.DeploymentService/*	ConnectRPC: executable deployment identity — registration and execution routing (ADR 0081). See Executable Deployments
/ironflow.v1.AuditService/*	ConnectRPC: history inspection (audit trail) queries
/ironflow.v1.TimeTravelService/*	ConnectRPC: history navigation (time-travel debugging)
/ironflow.v1.InstanceAdminService/*	ConnectRPC: instance barrier and drain administration, platform credentials only. See Instance barrier and drain administration
/ironflow.v1.AgentToolsService/*	ConnectRPC: agent tool registry (exposeMcp runtime, issue #595)

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