> ## 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.

# Start process by build id and process name

> Start a FlowX process from your own app or backend by specifying the appId, buildId, and process definition name.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps.md).

## Base URL

* Always prepend the endpoint with the correct Base URL.
* For different environments (like staging or production), switch the base URL accordingly.

## Path Parameters

> [!NOTE]
>
> **Need help finding these IDs?** See the [Finding Identifiers and Parameters](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters.md) guide for detailed instructions on where to locate these values in FlowX Designer.

> [!WARNING]
>
> The pair (`buildId`, `appId`) must be valid and associated in the system. The `workspaceId` is internally resolved using the `buildId` from the build collection.

**appId** `string` *required*

The ID of the application. Must form a valid pair with the `buildId`.

**buildId** `string` *required*

The build ID for the runtime environment. Must form a valid pair with the `appId`.

> [!TIP]
>
> When integrating from a frontend application or renderer, use the `buildId` value returned in the [build info response](https://docs.flowx.ai/6.x/docs/api/start-process/get-build-info.md).

**processDefinitionName** `string` *required*

The name of the process definition to start.

## Request headers

**Authorization** `string` *required*

Bearer token required for authentication. Format: `Bearer <token>`.

**Content-Type** `string` *required*

Indicates the media type of the request body. Must be set to `application/json`.

**Flowx-Platform** `string` *required*

Identifies the client platform (e.g., `web`).

**Accept** `string`

Specifies the media types that are acceptable for the response. Example: `application/json, text/plain, */*`.

**Accept-Encoding** `string`

Indicates supported content encoding algorithms for the response. Example: `gzip, deflate, br, zstd`.

**Accept-Language** `string`

Specifies language preferences for the response. Example: `en-GB,en-US;q=0.9,en;q=0.8`.

**User-Agent** `string`

Identifies the client software making the request (e.g., browser or tool).

**Referer** `string`

The address of the previous web page from which the request was made.

## Request Body

This endpoint requires a JSON request body. The exact payload structure should conform to the process definition schema associated with `{processDefinitionName}`.

**key1** `string` *required*

Description of what key1 represents

**key2** `string` *required*

Description of what key2 represents

### Example Request Body

```json theme={"dark"}
{
  "key1": "value1",
  "key2": "value2"
}
```

## Response

**processDefinitionFlowxUuid** `string`

The unique identifier of the process definition within FlowX.

**buildId** `string`

The ID of the build associated with the process.

**buildStatusAtStart** `string`

The status of the build at the time the process was started (e.g., "COMMITTED").

**applicationId** `string`

The ID of the application where the process was initiated.

**parentApplicationId** `string or null`

The ID of the parent application if applicable, otherwise `null`.

**rootApplicationId** `string or null`

The ID of the root application if applicable, otherwise `null`.

**processDefinitionName** `string`

The name of the process definition that was started.

**tokens** `array`

A list of tokens representing active workflow states within the process.

**state** `string`

The current state of the process instance (e.g., "STARTED").

**uuid** `string`

The unique identifier for the process instance.

**instanceMetadata** `object`

Metadata related to the process instance, including:

* `processInstanceId`: The numeric ID of the process instance.
* `processInstanceUuid`: The UUID of the process instance.

### Response Headers

**Access-Control-Allow-Credentials** `boolean`

Indicates whether the response can be exposed when credentials are present. Value is `true`.

**Access-Control-Allow-Headers** `string`

Lists the allowed headers in the actual request. Example: `DNT, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization, flowx-platform`.

**Access-Control-Allow-Methods** `string`

Specifies the allowed HTTP methods. Example: `GET, PUT, POST, DELETE, PATCH`.

**Access-Control-Allow-Origin** `string`

Indicates the allowed origin for cross-origin requests. Example: `https://demo-angular.devmain.flowxai.dev`.

**Content-Encoding** `string`

Specifies the encoding used to compress the response. Example: `gzip`.

**Content-Type** `string`

Indicates the media type of the response content. Example: `application/json`.

**Strict-Transport-Security** `string`

Enforces secure (HTTPS) connections to the server. Example: `max-age=31536000 ; includeSubDomains`.

**Vary** `string`

Specifies that the response may vary based on the `Accept-Encoding` request header. Example: `Accept-Encoding`.

**X-Content-Type-Options** `string`

Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`. Example: `nosniff`.

**X-XSS-Protection** `string`

Controls the cross-site scripting (XSS) filter. Example: `0` (disabled).

```bash theme={"dark"}
curl -X POST "https://admin.devmain.flowxai.dev/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start" \
  -H "Authorization: Bearer <token>" \                    # Required
  -H "Content-Type: application/json" \                   # Required
  -H "flowx-platform: web" \                              # Required
  -H "Accept: application/json, text/plain, */*" \        # Optional
  -H "Accept-Encoding: gzip, deflate, br, zstd" \         # Optional
  -H "Accept-Language: en-GB,en-US;q=0.9,en;q=0.8" \      # Optional
  -d '{
    "key": "value"
  }'
```


## Related topics

- [Start process by workspace, app, and process name](https://docs.flowx.ai/6.x/docs/api/start-process/start-by-process-name.md)
- [Consuming FlowX from external apps](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps.md)
- [Failed process start (exceptions)](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/failed-process-start.md)
- [Start integration workflow action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md)
- [Supported scripts](https://docs.flowx.ai/6.x/docs/building-blocks/supported-scripts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.