REST API Reference

Base URL: https://api.fyrn.dev/api/v1

All /api/v1/* routes require authentication via Auth0 JWT bearer token or API key. Public routes (health check, webhook receiver) are exempt.

Authentication

Include a bearer token in the Authorization header:

Authorization: Bearer <access_token>

Public paths that skip auth: /health, /webhooks/receive/, /inbound/.

Health

GET /health

Health check endpoint. No auth required.

{ "status": "ok" }

Flows

GET /api/v1/flows

List all flows for the current environment. Webhook-triggered flows include their full webhook URL.

Response: Array of flow objects with id, name, status, version, description, yamlConfig, webhookUrl.

POST /api/v1/flows

Create a new flow.

Body:

{
  "name": "my-flow",
  "description": "Sync orders",
  "yamlConfig": "flow: my-flow\nversion: 1\n..."
}

GET /api/v1/flows/:id

Get a single flow by ID. Returns full flow object including parsed config and compiled plan.

PUT /api/v1/flows/:id

Update a flow. Accepts name, description, yamlConfig, status, changeSummary.

DELETE /api/v1/flows/:id

Soft-delete a flow.

POST /api/v1/flows/:id/deploy

Deploy a flow — validates, compiles, activates, and creates a version snapshot.

Response: Deployed flow with webhook URL (if applicable).

POST /api/v1/flows/:id/pause

Pause an active flow.

POST /api/v1/flows/:id/resume

Resume a paused flow.

POST /api/v1/flows/:id/test

Test a flow with sample data. Applies the mapping without delivery.

Body:

{
  "sampleData": { "id": "ORD-001", "total": 99.99 }
}

GET /api/v1/flows/:id/versions

List version history for a flow.

POST /api/v1/flows/:id/rollback

Rollback to a previous version.

Body:

{ "versionNumber": 2 }

POST /api/v1/flows/:id/promote

Promote a flow from one environment to another.

Body:

{
  "targetEnvironmentId": "...",
  "notes": "Promoting to production after QA"
}

POST /api/v1/flows/:id/visualize

Get the execution plan as a directed graph for the pipeline visualizer.

AI Generation

POST /api/v1/ai/generate-flow

Generate a flow YAML from a natural language description.

Body:

{
  "description": "Sync Shopify orders to NetSuite",
  "sourceHint": "Shopify webhook",
  "targetHint": "NetSuite REST API",
  "errorHandling": "standard"
}

Response: Generated YAML config, suggested name, and description.

POST /api/v1/ai/generate-adapter

Generate adapter JavaScript code from a description.

Body:

{
  "description": "Convert XML order to JSON",
  "adapterType": "request_transform",
  "sampleInput": {}
}

POST /api/v1/ai/generate-published-api

Generate a published API configuration from a description.

POST /api/v1/ai/generate-test-payload

Generate a realistic test payload for a flow.

POST /api/v1/ai/analyze-error

Analyze a flow error and suggest fixes (self-healing).

Messages

GET /api/v1/messages

List messages for a flow.

Query params: flowId (required), status, since, search, limit, offset.

GET /api/v1/messages/:id

Get a single message with full trace.

POST /api/v1/messages/:id/retry

Retry a failed message.

POST /api/v1/messages/:id/replay

Replay a message through the full pipeline.

GET /api/v1/messages/stream

SSE endpoint for live message streaming.

Query params: flowId, status.

Connectors

GET /api/v1/connectors/catalog

List all connector catalog entries.

GET /api/v1/connectors/instances

List connector instances for the current environment.

POST /api/v1/connectors/instances

Create a new connector instance.

Body:

{
  "catalogId": "...",
  "name": "my-shopify",
  "displayName": "My Shopify Store",
  "config": { "store_url": "mystore.myshopify.com", "api_key": "..." }
}

GET /api/v1/connectors/instances/:id

Get a single connector instance (config fields redacted).

PUT /api/v1/connectors/instances/:id

Update a connector instance.

DELETE /api/v1/connectors/instances/:id

Soft-delete a connector instance.

POST /api/v1/connectors/instances/:id/test

Test a connector instance connection.

GET /api/v1/connectors/instances/:id/schemas

List tracked endpoint schemas for a connector instance.

OAuth

GET /api/v1/connectors/oauth/authorize

Start OAuth flow for a connector. Returns the authorization URL.

Query params: catalogId, instanceName, redirectUri.

GET /oauth/callback

OAuth callback handler. Exchanges authorization code for tokens.

Schedules

GET /api/v1/schedules

List all schedules.

Query params: flowId (optional).

PUT /api/v1/schedules/:id

Update a schedule — cron expression, timezone, enabled.

POST /api/v1/schedules/:id/trigger

Manually trigger a scheduled flow.

Lookup Tables

GET /api/v1/lookup-tables

List all lookup tables.

POST /api/v1/lookup-tables

Create a lookup table.

Body:

{ "name": "country-warehouses", "description": "Maps countries to warehouse IDs" }

GET /api/v1/lookup-tables/:id

Get a lookup table with entries.

Query params: search, limit.

DELETE /api/v1/lookup-tables/:id

Soft-delete a lookup table.

PUT /api/v1/lookup-tables/:id/entries

Add or update an entry.

Body:

{ "key": "US", "value": "warehouse-east-01" }

DELETE /api/v1/lookup-tables/:id/entries/:key

Delete an entry by key.

POST /api/v1/lookup-tables/:id/import

Import entries from CSV.

Body (multipart): CSV file with key and value columns.

GET /api/v1/lookup-tables/:id/export

Export entries as CSV.

Adapters

GET /api/v1/adapters

List all adapters.

POST /api/v1/adapters

Create an adapter.

GET /api/v1/adapters/:id

Get an adapter by ID.

PUT /api/v1/adapters/:id

Update an adapter.

DELETE /api/v1/adapters/:id

Soft-delete an adapter.

POST /api/v1/adapters/:id/test

Test an adapter with sample input.

Body:

{ "input": { "order_id": "ORD-123" } }

GET /api/v1/adapters/templates

List pre-built adapter templates.

Published APIs

GET /api/v1/published-apis

List published API endpoints.

POST /api/v1/published-apis

Create a published API.

GET /api/v1/published-apis/:id

Get a published API by ID.

PUT /api/v1/published-apis/:id

Update a published API.

DELETE /api/v1/published-apis/:id

Soft-delete a published API.

POST /api/v1/published-apis/:id/keys

Create a consumer API key.

GET /api/v1/published-apis/:id/keys

List consumer keys.

DELETE /api/v1/published-apis/:id/keys/:keyId

Revoke a consumer key.

GET /api/v1/published-apis/:id/versions

List API versions.

Batch Jobs

POST /api/v1/batch

Start a batch job.

Body:

{
  "flowId": "...",
  "records": [{"order_id": "ORD-001"}, {"order_id": "ORD-002"}],
  "concurrency": 10
}

GET /api/v1/batch/:id

Get batch job status and progress.

GET /api/v1/batch

List recent batch jobs.

Query params: flowId.

GET /api/v1/batch/:id/errors

Export batch job errors.

POST /api/v1/batch/:id/retry

Retry failed records in a batch job.

Self-Healing

GET /api/v1/healing

List healing events.

Query params: flowId.

GET /api/v1/healing/:id

Get a healing event by ID.

POST /api/v1/healing/:id/approve

Approve a pending healing fix.

POST /api/v1/healing/:id/reject

Reject a pending healing fix.

Environments

GET /api/v1/environments

List environments for the current account.

POST /api/v1/environments

Create an environment.

PUT /api/v1/environments/:id

Update an environment.

Alert Rules & Channels

GET /api/v1/alert-channels

List alert channels.

POST /api/v1/alert-channels

Create an alert channel.

GET /api/v1/alert-rules

List alert rules.

POST /api/v1/alert-rules

Create an alert rule.

PUT /api/v1/alert-rules/:id

Update an alert rule.

GET /api/v1/alert-history

List alert history.

Agent Keys

GET /api/v1/agent-keys

List agent API keys for MCP access.

POST /api/v1/agent-keys

Create an agent API key.

DELETE /api/v1/agent-keys/:id

Deactivate an agent key.

GET /api/v1/agent-actions

List pending agent actions awaiting approval.

POST /api/v1/agent-actions/:id/approve

Approve a pending agent action.

POST /api/v1/agent-actions/:id/reject

Reject a pending agent action.

Audit Log

GET /api/v1/audit-log

List audit log entries.

Query params: action, entityType, entityId, userId, limit, offset.

Auth

GET /api/v1/auth/me

Get the current authenticated user’s profile.

Flow Bundles

POST /api/v1/flows/:id/export

Export a flow as a ZIP bundle (YAML config, lookup tables, adapter code).

POST /api/v1/flows/import

Import a flow from a ZIP bundle.

Body (multipart): ZIP file.

Connector Actions

GET /api/v1/connectors/catalog/:catalogId/actions

List actions for a catalog entry.

GET /api/v1/connectors/catalog/:catalogId/actions/:slug

Get a specific action with full request/response schemas.

Schema Registry

GET /api/v1/connectors/instances/:id/schemas

List tracked endpoint schemas for a connector instance.

POST /api/v1/connectors/instances/:id/schemas/check

Trigger a schema check for a connector instance.

Search

GET /api/v1/search

Full-text search across flows, connectors, adapters, and published APIs.

Query params: q (search query), type (entity type filter), limit.

Account Members

GET /api/v1/members

List account members with roles.

POST /api/v1/members/invite

Invite a user to the account.

Body:

{ "email": "user@example.com", "role": "editor" }

PUT /api/v1/members/:id

Update a member’s role.

DELETE /api/v1/members/:id

Remove a member from the account.

Usage

GET /api/v1/usage

Get current period usage (messages processed, AI actions consumed, active flows, connectors, environments).

Billing

GET /api/v1/billing/status

Get current plan, subscription status, and payment info.

POST /api/v1/billing/checkout

Create a Stripe checkout session for plan upgrade.

Body:

{ "plan": "team", "interval": "annual" }

GET /api/v1/billing/portal

Get a Stripe customer portal URL for managing billing.

Governance

GET /api/v1/governance/policies

List governance policies.

GET /api/v1/governance/policies/:id

Get a governance policy by ID.

POST /api/v1/governance/check

Check flow compliance against policies.

Body:

{ "flowId": "..." }

Webhook Receiver

POST /webhooks/receive/:path

Inbound webhook endpoint. No auth required (uses path-based routing with optional secret token verification).

POST /published/:path

Published API inbound endpoint. Auth via consumer API key.