> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Consuming FlowX from external apps

> Choose the right integration pattern when calling FlowX from your own code — embed the UI with the SDKs, trigger processes via REST or webhooks, drive events through Kafka, or react to events downstream.

This guide is for developers who want to integrate FlowX with their **own application or backend** — for example, embedding a FlowX-driven UI inside a React app, triggering a FlowX process from a backend job, or reacting to FlowX events in a downstream system.

Pick the pattern that matches what you are trying to do. Each section links to the reference docs for setup details.

<Warning>
  **Do not poll renderer-internal runtime endpoints from your own code.**

  Endpoints under `/api/runtime/process/.../status` and `/api/runtime/process/.../data` exist for the FlowX renderers (React / React Native / Angular / iOS / Android SDKs) to refresh their own state. They are not part of the public integration surface and their contracts can change between releases without notice. If you need process state in your own app, use one of the patterns below instead.
</Warning>

***

## Choose your pattern

| If you want to…                                                              | Use this pattern                                                    | Why                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------- |
| Show FlowX-driven screens inside your existing web or mobile app             | [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk)                   | Handles state, validation, UI updates for you |
| Start a FlowX process from your backend, a scheduled job, or another service | [Public REST API](#2-trigger-a-process-via-rest)                    | Stable, documented, public endpoints          |
| Start a FlowX process when an external system fires an HTTP callback         | [Incoming Webhook](#3-trigger-a-process-from-an-incoming-webhook)   | No backend code needed; FlowX exposes the URL |
| Start a FlowX process from an event your other services already publish      | [Kafka custom integration](#4-trigger-a-process-from-a-kafka-event) | Fits event-driven architectures               |
| React to FlowX activity from a downstream system                             | [Kafka events outbound](#5-react-to-flowx-events)                   | Decoupled, stream-based                       |

***

## 1. Embed the FlowX UI with an SDK

Use a renderer SDK to render FlowX-driven UI flows and process screens inside your app. The SDK manages session state, polling, and form lifecycle — you do not need to call runtime endpoints directly.

<CardGroup cols={2}>
  <Card title="React Renderer" icon="react" href="/5.9/sdks/react-renderer">
    Embed FlowX flows in a React application
  </Card>

  <Card title="React Native Renderer" icon="react" href="/5.9/sdks/react-native-renderer">
    Embed FlowX flows in a React Native application
  </Card>

  <Card title="Angular Renderer" icon="angular" href="/5.9/sdks/angular-renderer">
    Embed FlowX flows in an Angular application
  </Card>

  <Card title="iOS Renderer" icon="apple" href="/5.9/sdks/ios-renderer">
    Embed FlowX flows in a native iOS app
  </Card>

  <Card title="Android Renderer" icon="android" href="/5.9/sdks/android-renderer">
    Embed FlowX flows in a native Android app
  </Card>
</CardGroup>

**Use this when:** the UI your end users see should be driven by FlowX (forms, screens, navigation, validation).

**Do not use this when:** you only need a backend/server-to-server integration with no UI.

***

## 2. Trigger a process via REST

Start a process programmatically from any HTTP-capable code (backend service, CLI, scheduled job, partner system).

<Steps>
  <Step title="Get the build info">
    Call **[Get Build Info](/5.9/docs/api/start-process/get-build-info)** with the workspace ID and app ID to retrieve the active `buildId`. The active policy determines which build is currently live for the runtime.
  </Step>

  <Step title="Start the process">
    Call **[Start process by build id and process name](/5.9/docs/api/start-process/rest2)** with the `appId`, `buildId`, and process definition name. The response contains the new process instance UUID.

    For UI-action scenarios where the process should inherit a resource definition from a related instance, see [Start with resource definition and inherit values](/5.9/docs/api/start-process/start-process-rdi-inherit).
  </Step>

  <Step title="Locate the IDs you need">
    If you do not know your `workspaceId`, `appId`, or process definition name, see the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide.
  </Step>
</Steps>

**Use this when:** another service needs to kick off a FlowX process and the user-facing UI (if any) is handled separately.

**Do not use this when:** you are tempted to keep polling the runtime to track the process — switch to Kafka events or use the SDK instead.

***

## 3. Trigger a process from an incoming webhook

If the external system can call an HTTP endpoint, FlowX exposes a Webhook Gateway URL per resource definition. The system POSTs to the URL, FlowX starts the process. No code on your side beyond configuring the call.

<Card title="Incoming Webhooks" icon="webhook" href="./incoming-webhooks">
  Configure webhook-triggered processes, secure them with API keys
</Card>

**Use this when:** integrating with a third-party SaaS that supports outbound webhooks (Slack, GitHub, payment providers, custom apps).

**Do not use this when:** the calling system is your own backend that already speaks Kafka — pattern 4 is more efficient.

***

## 4. Trigger a process from a Kafka event

Build a custom integration (Connector microservice) that publishes to a Kafka topic the FlowX engine listens on, or wire an existing event stream into the engine through a topic naming convention.

<Card title="Custom integrations and Kafka topics" icon="message" href="./integrations-overview">
  Custom integrations overview, topic naming, Connector quickstart
</Card>

**Use this when:** your architecture is already event-driven and you want FlowX to react to events alongside other consumers.

***

## 5. React to FlowX events

Run a downstream service that consumes Kafka events emitted by the FlowX engine — for example, audit forwarding, metrics, or notifications.

See the [custom integrations overview](./integrations-overview) for topic naming and event types.

**Use this when:** you need to mirror or transform FlowX activity into another system without coupling it to a synchronous API call.

***

## Authentication

All public REST endpoints require a Bearer token issued by the configured identity provider (Keycloak by default). See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for setup, and the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide for retrieving the values you need to authenticate from outside the platform.

<Note>
  The reference pages linked above cover the most common public endpoints (build info + process start variants). FlowX exposes additional public endpoints — for example, starting workflows, fetching task views, and retrieving public data-model paths — that are not yet documented end-to-end. If you need one of those, contact the platform team and we will add it to the reference set.
</Note>

***

## Frequently asked

<AccordionGroup>
  <Accordion title="How do I know when a process I started has finished or what data it produced?">
    Do not poll runtime query endpoints from your own code. The supported approaches are:

    * If you need real-time process state in a UI, use a [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk) — it handles state for you.
    * If you need to react to completion in another service, consume the relevant Kafka event (see pattern 5).
    * If you need a callback to your own HTTP endpoint, model that as an explicit step in the process (a Service Task that calls your URL when the process reaches that node).
  </Accordion>

  <Accordion title="Can I build my entire UI in React without using the FlowX renderer?">
    You can, but you will not get FlowX's UI state management, validation, navigation, or form generation — those live inside the renderer. If you only need to start processes from a custom UI (not render FlowX-driven screens), pattern 2 is enough. If you need FlowX-driven screens, use the React Renderer.
  </Accordion>

  <Accordion title="Where do I find my appId and buildId?">
    See the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide. The `buildId` returned from [Get Build Info](/5.9/docs/api/start-process/get-build-info) is the one to use when starting a process from a frontend or external app.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Public REST API reference" icon="code" href="/5.9/docs/api/start-process/get-build-info">
    Endpoint specs for build info and starting processes
  </Card>

  <Card title="SDKs overview" icon="puzzle-piece" href="/5.9/sdks/sdks-overview">
    React, React Native, Angular, iOS, Android renderer SDKs
  </Card>

  <Card title="Incoming Webhooks" icon="webhook" href="./incoming-webhooks">
    Trigger processes from external HTTP callbacks
  </Card>

  <Card title="Custom integrations" icon="gears" href="./integrations-overview">
    Kafka-based Connectors and topic naming
  </Card>
</CardGroup>