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 /api/v1/events - Emit an event
• GET /api/v1/functions - List registered functions
• GET /api/v1/runs - List runs
• GET /api/v1/runs/{id} - Get run details
• GET /api/v1/streams - List all entity streams
• POST /api/v1/sql - Execute read-only SQL query
• POST /api/v1/projections/{name}/pause - Pause projection
• POST /api/v1/projections/{name}/resume - Resume projection
• DELETE /api/v1/projections/{name} - Delete projection
• POST /api/v1/events/schemas - Register event schema
• GET /api/v1/events/schemas - List event schemas
• 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/sdk/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.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.