# Flowyn

> Flowyn is API-first infrastructure for applications and AI agents. Five primitives — Process, Execute, Connect, Observe, and Configure — cover the work around your code: documents, durable HTTP jobs and schedules, reliable webhooks, monitoring, and flags. Agent infrastructure builds on them for agents you build and deploy yourself: Flowyn records each agent's identity, runs, traces and steps, model usage and cost, and human approval decisions. Flowyn is the infrastructure around your agent, not the intelligence inside it.

Flowyn is NOT an agent framework, a model provider or inference host, an agent runtime, a vector database or agent memory, a no-code workflow builder, or a Zapier replacement. It does not host or execute your agent's code, proxy your model calls, store prompts or completions, orchestrate multiple agents, or pause, resume, signal, or cancel a running agent.

- API base URL: https://api.flowyn.dev
- OpenAPI 3 document (authoritative contract): https://api.flowyn.dev/openapi/v1.yaml
- Authentication: `Authorization: Bearer <api key>`. Keys are shown once and belong server-side. Test keys start with `flw_test_`, live keys with `flw_live_`. Abilities: read, run, reveal.
- Creates accept an `Idempotency-Key` header (24-hour window). Delivery and execution are at-least-once; receivers deduplicate on the stable id Flowyn sends (`Idempotency-Key: <job id>` on HTTP jobs, `webhook-id` on webhooks).
- Capabilities: GET https://api.flowyn.dev/v1/capabilities (all five primitives and existing Agent capabilities; missing interface names mean use REST).
- Every docs page as Markdown: https://flowyn.dev/llms-full.txt

## Primitives

- PROCESS — Documents and files: upload with tus (`POST /v1/files`), PDF parse to text, Markdown, or JSON (`POST /v1/pdf/parse`), DOCX parse (`POST /v1/docx/parse`), HTML file to PDF (`POST /v1/pdf/from-html`), intelligent PDF split (`POST /v1/split-pdf`). Asynchronous: HTTP 202 with a file job, up to 3 attempts. No OCR. 50 MB and 200 pages per file. https://flowyn.dev/process
- EXECUTE — Durable HTTP jobs (`POST /v1/jobs`): stored first, retried on timeouts, 408, 429, and 5xx with exponential backoff (1–20 attempts), every attempt recorded, cancellable. Cron schedules in a timezone (`POST /v1/schedules`); each occurrence creates an ordinary job; missed occurrences are skipped. https://flowyn.dev/execute
- CONNECT — Events and webhooks (`POST /v1/events`): stored first, signed in the Standard Webhooks format, up to 8 delivery attempts from 5 seconds to 10 hours apart, replayable (`POST /v1/events/{id}/replay`). Endpoints with signing secrets and test deliveries (`POST /v1/endpoints`). https://flowyn.dev/connect
- OBSERVE — Monitors (`POST /v1/monitors`): HTTP checks, heartbeats (`POST /v1/monitors/{id}/ping`), and API checks with assertions; incidents after three consecutive failures and recovery. Issues group repeated failures (`GET /v1/issues/{fingerprint}`). https://flowyn.dev/observe
- CONFIGURE — API keys and deterministic feature flags and remote configuration (`POST /v1/flags/evaluate`): typed values per environment, ordered rules, percentage rollouts on a stable identifier, and a reason with every result. https://flowyn.dev/configure

## Agent infrastructure

For agents built with any framework (OpenAI Agents SDK, LangGraph, CrewAI, Mastra, PydanticAI, custom Python or Node.js) and deployed anywhere. The agent calls Flowyn's REST API; there is no plugin. https://flowyn.dev/agents

- Agent registry (`POST /v1/agents`): a durable identity for each externally deployed agent — name, description, your external_id; active or archived; up to 100 active agents per environment.
- Agent runs (`POST /v1/agent-runs`, `POST /v1/agent-runs/{id}/finish`): a record of each execution your runtime reports — running, then exactly one of succeeded, failed, or cancelled. Flowyn records the run; it does not run, queue, retry, or cancel it.
- Traces and steps (`POST /v1/agent-telemetry`, `GET /v1/agent-telemetry/{trace_id}`): batches of up to 50 spans with W3C-format trace and span ids. A trace whose root span carries a run_id makes its spans the run's steps: generation = model step, tool = tool step, span = generic operation, with hierarchy, status, timing, and errors. Metadata only: no prompts, completions, tool arguments, or tool results. Kept 30 days.
- Model usage and cost (`GET /v1/agent-telemetry/usage`): input, output, and cached tokens, latency, and reported or estimated USD cost per step, per trace, and grouped by model, provider, service, or step name over 1 hour to 30 days. Estimates use Flowyn's price catalog of selected OpenAI, Anthropic, and Google models; unknown cost is reported as unavailable, never zero; not an invoice.
- Advisory Agent warnings: nullable `token_warning_24h` and decimal-string `cost_warning_24h_usd` on Agent create/PATCH; null disables, PATCH omitted preserves and explicit null clears, with `expected_revision` and `Idempotency-Key`. `GET /v1/agent-telemetry/usage?agent_id=<id>&last=24h` evaluates warnings on request when observed >= threshold. Attribution follows the scoped trace root, including child generation spans without agent_id. Rootless/unlinked traces are excluded and disclosed; future spans excluded from `[from, evaluated_at)`. Reported cost precedes stored estimates; missing tokens and unpriced contributions remain visible. Other windows are analysis only. No remaining balance, spending enforcement, or external-runtime restriction.
- Human approvals (`POST /v1/agent-approvals`, `GET /v1/agent-approvals/{id}`): the agent's runtime asks for a decision about one action of a running run; a signed-in person approves or rejects it in the Flowyn dashboard (API keys cannot decide); the runtime polls, reads the decision, and decides how to continue. Flowyn is the durable decision service; it does not block, pause, resume, or enforce anything.
- Provider connections (`POST /v1/provider-connections`): an OpenAI API key stored encrypted per environment, write-only, with an explicit connection test against OpenAI. Optional — agents can keep calling any provider with their own keys.

## Docs

- Quickstart: https://flowyn.dev/docs/getting-started/quickstart
- Authentication: https://flowyn.dev/docs/getting-started/authentication
- Idempotency and retries: https://flowyn.dev/docs/getting-started/idempotency
- Errors: https://flowyn.dev/docs/getting-started/errors
- REST API reference: https://flowyn.dev/docs/tools/rest
- Coding agents (OpenAPI, llms.txt, SDK, CLI, MCP): https://flowyn.dev/docs/tools/agents
- Limits and credits: https://flowyn.dev/docs/tools/limits
- PDF parse: https://flowyn.dev/docs/process/pdf-parse
- Durable HTTP jobs: https://flowyn.dev/docs/execute/jobs
- Schedules: https://flowyn.dev/docs/execute/schedules
- Events and webhooks: https://flowyn.dev/docs/connect/events
- Monitors: https://flowyn.dev/docs/observe/monitors
- Heartbeats: https://flowyn.dev/docs/observe/heartbeats
- Issues: https://flowyn.dev/docs/observe/issues
- Flags: https://flowyn.dev/docs/configure/flags

## Agent docs

- Overview and quickstart (register, run, trace, usage, approval, finish): https://flowyn.dev/docs/agents/overview
- Agents and runs: https://flowyn.dev/docs/agents/registry-and-runs
- Traces and steps: https://flowyn.dev/docs/agents/telemetry
- Model usage and cost: https://flowyn.dev/docs/agents/model-usage
- Human approvals: https://flowyn.dev/docs/agents/approvals
- Provider connections: https://flowyn.dev/docs/agents/provider-connections

## Guides

- Reliable webhooks and how retries work: https://flowyn.dev/docs/guides/how-webhook-retries-work
- Designing idempotent API operations: https://flowyn.dev/docs/guides/designing-idempotent-api-operations
- Heartbeat monitoring for cron jobs: https://flowyn.dev/docs/guides/heartbeat-monitoring-for-cron-jobs

## Use cases

- Reliable webhooks: https://flowyn.dev/use-cases/reliable-webhooks
- Document and PDF API: https://flowyn.dev/use-cases/document-processing-api
- Scheduled HTTP requests: https://flowyn.dev/use-cases/scheduled-http-requests

## Terminology

- Environment: test or live; every resource and key belongs to one.
- Job: a durable HTTP request with attempts. File job: an asynchronous document operation.
- Event: a stored message delivered to endpoints as signed webhooks. Attempt: one recorded delivery or execution try.
- Issue: repeated failures grouped by fingerprint. Incident: a monitor's open failure period.
- Agent: a registered identity for an agent you deploy. Run: a record of one execution your runtime reports. Trace / span: telemetry; spans of a run-linked trace are the run's steps. Approval: a human decision your runtime reads.

## Tools

- Node SDK, CLI, and stdio MCP server live in the Flowyn repository. The Node SDK covers existing Agent APIs through agents, agentRuns, telemetry, approvals, and providerConnections; CLI/MCP keep their existing primitive tools. Approval decisions remain human-session-only. They are not published to a package registry, and MCP is not hosted.

- Source setup: Node >= 22.13, pnpm 11.21.0; from the root run `pnpm install --frozen-lockfile`, `pnpm --filter @flowyn/cli build`, then `pnpm flowyn context` with server-side FLOWYN_API_KEY. FLOWYN_BASE_URL selects a different API deployment; keys own workspace/environment scope.
- MCP client: launch `node /absolute/path/to/flowyn/packages/cli/dist/index.js mcp --preset read` with server-side FLOWYN_API_KEY. The process lives until stdio closes. Start with session_context and discover_capabilities. Writes require explicit write mode and live writes also require --allow-live.
- SDK recovery: uncertain-write errors preserve idempotencyKey; retry the identical operation/body with that same key. Preserve next, retryAfterSeconds, requestId and errorId. Canonical errors: https://flowyn.dev/docs/getting-started/errors.

## Pricing

- Starter: $0, 10,000 credits a month.
- Production: $9/month, 200,000 credits a month.
- Capacity: $39/month, 1,000,000 credits a month.
- https://flowyn.dev/pricing

## Optional

- Playground: https://flowyn.dev/playground
- Support: https://flowyn.dev/contact