Crate ironflow_api 

ironflow-api

REST API crate for the ironflow workflow engine. Provides endpoints for querying workflow runs, managing their lifecycle, and viewing aggregate statistics.

Architecture

• actor.rs — Maps an authenticated caller to a persisted run author
• entities/ — DTOs and query parameter types (public API contract)
• routes/ — One file per route handler
• error.rs — Typed API errors mapped to HTTP status codes
• response.rs — Standard response envelope
• state.rs — Shared application state

API Endpoints

Health check

• GET /api/v1/health-check — Liveness probe, always returns 200 OK

Runs

• GET /api/v1/runs — List runs with optional filtering and pagination
• POST /api/v1/runs — Trigger a workflow
• GET /api/v1/runs/:id — Get run details and steps
• POST /api/v1/runs/:id/cancel — Cancel a pending or running run
• POST /api/v1/runs/:id/retry — Retry a failed run (creates new run)
• POST /api/v1/runs/:id/replay – Replay a finished run on the current handler version (creates new run)

Workflows

• GET /api/v1/workflows — List registered workflows

Statistics

• GET /api/v1/stats — Aggregate statistics (total runs, success rate, cost, etc.)

Events (SSE)

• GET /api/v1/events — Server-Sent Events stream for real-time updates

Quick start

use ironflow_api::prelude::*;
use ironflow_api::routes::{RouterConfig, create_router};
use ironflow_store::prelude::*;
use ironflow_engine::engine::Engine;
use ironflow_core::providers::claude::ClaudeCodeProvider;
use ironflow_auth::jwt::JwtConfig;
use std::sync::Arc;

let store: Arc<dyn Store> = Arc::new(InMemoryStore::new());
let provider = Arc::new(ClaudeCodeProvider::new());
let engine = Arc::new(Engine::new(store.clone(), provider));
let jwt_config = Arc::new(JwtConfig {
    secret: "your-secret-key".to_string(),
    access_token_ttl_secs: 900,
    refresh_token_ttl_secs: 604800,
    cookie_domain: None,
    cookie_secure: false,
});
let broadcaster = ironflow_api::sse::SseBroadcaster::new();
let state = AppState::new(store, engine, jwt_config, "token".to_string(), broadcaster.sender());
let app = create_router(state, RouterConfig::default());

let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
    .await
    .unwrap();
axum::serve(listener, app).await.unwrap();

Re-exports

pub use routes::RouterConfig;

pub use routes::create_router;

pub use state::AppState;

Modules

actor

Mapping from an authenticated caller to a persisted run author.

config

Server configuration with startup validation.

entities

API entities — DTOs and query parameter types.

error

REST API error types and responses.

escalator

Resolution of approval gates that missed their SLA deadline.

middleware

Middleware for internal route protection and HTTP security hardening.

prelude

Convenience re-exports for common API usage.

purger

Retention-based purging of old runs and their artifacts.

rate_limit

Identity-aware rate limiting middleware.

reaper

Recovery of runs abandoned by a dead worker.

response

Standard response types and helpers for the REST API.

routes

Router assembly — one module per route.

schedule_sync

Reconciliation of handler-declared schedules with the database.

schedule_ticker

Unified schedule executor for all workflow schedules.

sse

Server-Sent Events broadcaster for real-time event streaming.

state

Application state and dependency injection.