Real-time Workflow API

The Middle real-time workflow API lets an external system run a Middle workflow and receive its result in the same HTTP request.

Quick start

To call a workflow through the API:

1. Create an API key in the account that owns the workflow endpoint.

2. Create a real-time workflow API endpoint and link the API key to it.

3. Copy the generated invoke URL.

4. Send a JSON object to that URL with the API key in the Authorization header.

Create an API key

1. Open the account in Middle.

2. Select API keys in the account navigation.

3. Select Add API key.

4. Enter a descriptive name for the calling system, such as Rewards service.

5. Leave Active on and select Save.

6. Copy the secret immediately and store it in your secret manager.

The secret is shown only once. Middle cannot display it again after you leave or refresh the page. If it is lost, rotate the key or create a new key.

Treat the entire value as a secret. Do not put it in a URL, query parameter, source control, browser-side code, or logs.

What an API key grants access to

An API key belongs to a single Middle account and can

• list the live workflow API endpoint configurations authorized for it

• call only the endpoints to which it is explicitly linked

For the key to authorize a call, all three of these access records must be active:

• the API key

• the real-time workflow API endpoint

• the workflow's real-time API trigger

One key can be linked to multiple endpoints, and one endpoint can accept multiple keys. This makes it possible to give different calling systems different access and to replace keys without interrupting traffic.

Authentication

Send the API key in the HTTP Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Endpoints

The real-time workflow API has two endpoints that you can call:

• GET /api/workflow-invoke-options/ lists the live endpoints authorized for the key.

• POST /api/workflow-invoke/{path_token}/ runs the workflow for one endpoint.

The list endpoint returns one option per endpoint, including the workflow name, invoke URL, input shape, and output shape. The same workflow name may appear more than once when different module connections expose it. The endpoint does not list every workflow in the account.

List the workflow endpoints available to a key

Use the discovery endpoint to list the live endpoint configurations linked to an API key. This is also the easiest way to inspect each target workflow's input and output types.

curl --request GET \
  --url 'https://test.middle.app/api/workflow-invoke-options/' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Example response:

{
  "success": true,
  "endpoint_options": [
    {
      "script_graph_api_endpoint_id": 321,
      "workflow_name": "Redeem a reward",
      "invoke_url": "https://test.middle.app/api/workflow-invoke/PATH_TOKEN/",
      "input_object": {
        "attribute_type": "object",
        "children": [
          {
            "key": "input_record",
            "attribute_type": "foreign_key",
            "display_name": "Input record"
          },
          {
            "key": "customer_email",
            "attribute_type": "string",
            "display_name": "Customer email"
          },
          {
            "key": "reward_name",
            "attribute_type": "string",
            "display_name": "Reward name"
          }
        ]
      },
      "output_object": {
        "attribute_type": "object",
        "children": [
          {
            "key": "reward_granted",
            "attribute_type": "boolean",
            "display_name": "Reward granted"
          },
          {
            "key": "confirmation_id",
            "attribute_type": "string",
            "display_name": "Confirmation ID"
          }
        ]
      }
    }
  ]
}

The response includes only endpoints linked to this key whose endpoint and trigger are both active. A valid key with no available endpoints receives an empty endpoint_options array.

Discovery does not revalidate the workflow itself. Invocation separately checks that the workflow has a live, API-eligible version. A discovered endpoint can therefore still return WORKFLOW_NOT_LIVE or WORKFLOW_NOT_API_ELIGIBLE when called.

The input_object and output_object values may be null when a workflow does not define the corresponding type information.

Invoke a workflow

Send a POST request to /api/workflow-invoke/{path_token}/ using the generated invoke URL returned by the list endpoint or displayed in Middle. The request body must be a JSON object, even when the workflow has no inputs.

curl --request POST \
  --url 'https://test.middle.app/api/workflow-invoke/YOUR_PATH_TOKEN/' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "input_record": null,
    "customer_email": "[e-mail]",
    "reward_name": "Free smoothie"
  }'

Example successful response:

{
  "success": true,
  "output": {
    "reward_granted": true,
    "confirmation_id": "reward-abc123"
  },
  "workflow_report_url": "https://test.middle.app/account/1/workflow-history/98765/"
}

The value of output is defined by the workflow's Return step. It may be an object, array, string, number, boolean, or null.

The report URL opens the saved workflow execution in Middle. Viewing that page requires normal Middle user access; the API key does not grant access to the user interface.

Input handling and warnings

The workflow's Begin step defines the accepted top-level input keys.

• A declared key that is present is passed to the workflow.

• A declared key that is missing is set to null and produces a warning.

• An undeclared key is ignored and produces a warning.

The discovery metadata describes the intended value types. Middle normalizes top-level keys before execution, but it does not pre-validate every value against those types. An incorrectly typed value may cause the workflow to fail.

A workflow can succeed and still return warnings:

{
  "success": true,
  "output": {
    "reward_granted": false,
    "confirmation_id": null
  },
  "workflow_report_url": "https://test.middle.app/account/1/workflow-history/98766/",
  "warnings": [
    "Input key \"reward_name\" was not provided; null was used.",
    "Input key \"debug\" was ignored."
  ]
}

The maximum request body is 256 KiB. The complete successful response, including the output and response envelope, is also limited to 256 KiB.

Errors

Handled errors use a consistent JSON envelope:

{
  "success": false,
  "error_code": "AUTHENTICATION_FAILED",
  "error_message": "The provided API key is invalid for this endpoint."
}

An error that occurs after workflow execution begins also includes workflow_report_url. When applicable, it may include warnings as well.

Common invoke endpoint responses include:

HTTP status	Error code	Meaning
401	INVALID_AUTHORIZATION_HEADER	The Bearer header is missing or malformed.
401	AUTHENTICATION_FAILED	The key cannot call this invoke URL.
400	API_ENDPOINT_NOT_FOUND	The path token does not match an endpoint.
400	API_ENDPOINT_NOT_LIVE	The account deactivated the endpoint.
400	API_TRIGGER_NOT_LIVE	The workflow API trigger is inactive.
400	INVALID_JSON	The request body is not valid JSON.
400	INVALID_REQUEST_BODY	The JSON value is not an object.
400	REQUEST_TOO_LARGE	The request exceeds 256 KiB.
400	WORKFLOW_NOT_LIVE	The workflow has no live version.
400	WORKFLOW_NOT_API_ELIGIBLE	The live workflow violates an API rule.
400	RESPONSE_TOO_LARGE	The successful response would exceed 256 KiB.
400	WORKFLOW_EXECUTION_FAILED	The workflow did not complete successfully.

A workflow failure may return a more specific execution error code instead of WORKFLOW_EXECUTION_FAILED. Treat every response with success: false as a failure.

The discovery endpoint returns 401 for a missing or malformed Bearer header. It currently returns 400 with AUTHENTICATION_FAILED for an invalid or inactive key.

Each request that reaches workflow execution, including a repeated request, starts a new workflow execution. The API does not accept an idempotency key, so only retry automatically when the workflow is safe to run more than once.

Configure a real-time workflow API endpoint

An API key does not expose a workflow by itself. An account must create an endpoint and link one or more API keys to it.

Expose an account workflow

1. Open the account and select Workflow triggers.

2. Find Real-time workflow API endpoints.

3. Select Add real-time workflow API endpoint.

4. Select the workflow to expose.

5. Select the API keys that may call it.

6. Select Create.

7. Copy the generated Invoke URL.

The new endpoint is active immediately. Creation requires at least one linked, active API key. The account can later edit the linked keys, deactivate the endpoint, delete it, or rotate its path token.

Rotating a path token immediately changes the invoke URL. It does not rotate any API keys.

Workflow requirements

A real-time API workflow runs synchronously: the HTTP request waits for the live workflow version to finish, and the Return step supplies the response's output value.

An eligible workflow must:

• have a live version;

• contain exactly one Return step;

• not contain a Bulk workflow execution step;

• not contain a File export step;

• not contain a Create or update record step;

• use only actions whose Lambda timeout is known and no more than 8 seconds.

The API runs actions inline and cannot pause for asynchronous child work. Because the caller waits for the entire workflow, design real-time workflows to finish quickly.

Real-time workflow API triggers and modules

Modules separate the reusable workflow definition from each account's decision to expose it.

What the module author configures

The module author:

1. Creates an eligible workflow in the module and makes a version live.

2. Opens the module's Workflow triggers page.

3. Adds an active Real-time workflow API trigger for that workflow.

The trigger says that connected accounts may expose the workflow. It does not create a public URL, create an API key, or grant an account access by itself.

What the connected account configures

Each connected account opts in separately:

1. Open the account and select Workflow triggers.

2. Find Real-time workflow API endpoints from modules.

3. Select Connect real-time workflow API endpoint from module.

4. Select the module connection, or account-specific installation, to use.

5. Select one of the real-time workflow API triggers defined by that module.

6. Select one or more API keys owned by the account.

7. Select Create and copy the generated invoke URL.

When the URL is called, Middle runs the module workflow in the context of that specific module connection. The workflow uses the app connections and module variables configured for that installation.

As a result:

• each endpoint belongs to one account and targets one module connection;

• each account manages its own invoke URLs and API keys;

• one account's key cannot call another account's module endpoint;

• the same module workflow can use different app connections and variables for each module connection, including multiple connections in one account;

• disabling the module's trigger stops calls through every account endpoint that uses it;

• disabling an account endpoint or key affects only that account.

If a module feature requires a real-time workflow API trigger, its setup is not ready until the module trigger is active and the account has a live endpoint for that module connection with at least one linked, active API key. Middle reports the missing setup, but does not create the key or URL automatically.

Public callers use the same discovery and invoke requests for account-owned and module-owned workflows. No module-specific headers or request envelope are required.

Rotate or revoke access

Rotate a key immediately

Open the key and select Rotate secret. The old secret stops working immediately, and the replacement is shown once. The key remains linked to the same endpoints.

Replace a key without interrupting traffic

1. Create a second active API key.

2. Link both the old and new keys to each required endpoint.

3. Update the calling system to use the new key.

4. Confirm the new key's Last used value updates.

5. Deactivate or delete the old key.

Deactivating a key immediately rejects it but preserves its endpoint links. Reactivating it restores those grants. Deleting a key permanently removes its endpoint links.