Act

{
  "connectionKey": "hubspot-prod",
  "api": {
    "method": "POST",
    "path": "/crm/v3/objects/contacts",
    "body": { "properties": { "email": "jane@example.com" } }
  }
}

{
  "connectionKey": "hubspot-prod",
  "code": "module.exports = async ({ input, membrane }) => ({ ok: true })",
  "input": {}
}

{
  "key": "create-contact",
  "integrationKey": "hubspot",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" }
}

{
  "id": "action_abc",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" },
  "meta": { "source": "support-ticket-1234" }
}

{
  "output": {},
  "actionRunId": "<string>"
}

POST

act

{
  "connectionKey": "hubspot-prod",
  "api": {
    "method": "POST",
    "path": "/crm/v3/objects/contacts",
    "body": { "properties": { "email": "jane@example.com" } }
  }
}

{
  "connectionKey": "hubspot-prod",
  "code": "module.exports = async ({ input, membrane }) => ({ ok: true })",
  "input": {}
}

{
  "key": "create-contact",
  "integrationKey": "hubspot",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" }
}

{
  "id": "action_abc",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" },
  "meta": { "source": "support-ticket-1234" }
}

{
  "output": {},
  "actionRunId": "<string>"
}

POST /act is Membrane’s unified entry point for running an action through a connection. See the Actions guide for the conceptual walkthrough — this page is the endpoint reference.

Dispatch styles

Exactly one of id, key, api, or code per call. Sending more than one returns 400.

Field	Style	When to use
`api`	Inline `api`	Make an ad-hoc HTTP request through the connection’s auth and base URL.
`code`	Inline `code`	Run a JavaScript snippet in a sandbox with a pre-wired authenticated `membrane` client.
`key`	Reusable	Run a saved (workspace- or integration-level) action by its stable key.
`id`	Reusable	Run a catalog action or a saved action by its Membrane ID.

Resolving a connection

Every dispatch needs a connection. Membrane resolves one in this order:

connectionId — direct.
connectionKey — look up by key.
integrationId or integrationKey — use that integration’s default connection.
Workspace default connection.

Reusable-action dispatches that target a connection-scoped or integration-scoped action use the action’s own scope automatically — the body fields above only kick in when the action’s scope doesn’t already resolve a connection. For inline dispatches (api / code), the connection must resolve to something — otherwise the request returns 400.

Request body

{
  "connectionKey": "hubspot-prod",
  "api": {
    "method": "POST",
    "path": "/crm/v3/objects/contacts",
    "body": { "properties": { "email": "jane@example.com" } }
  }
}

{
  "connectionKey": "hubspot-prod",
  "code": "module.exports = async ({ input, membrane }) => ({ ok: true })",
  "input": {}
}

{
  "key": "create-contact",
  "integrationKey": "hubspot",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" }
}

{
  "id": "action_abc",
  "connectionKey": "hubspot-prod",
  "input": { "email": "jane@example.com" },
  "meta": { "source": "support-ticket-1234" }
}

Field	Type	Description
`api`	object	Inline HTTP spec — `{ method, path, body?, headers?, query? }`.
`code`	string	Inline JS module body, executed in a sandbox.
`key`	string	Action key. Scope with `integrationKey`/`integrationId`/`connectionId` if non-unique.
`id`	string	Action ID. Mutually exclusive with `key` / `api` / `code`.
`connectionId`	string	Connection to run against. See resolution priority.
`connectionKey`	string	Connection key alternative to `connectionId`.
`integrationId`	string	Integration ID — used to scope `key` lookups or pick a default connection.
`integrationKey`	string	Integration key alternative to `integrationId`.
`input`	object	Action input. For reusable-action dispatches, validated against the action’s `inputSchema`.
`meta`	object	Arbitrary metadata stored on the resulting Action Run Log.

Response

{
  "output": { "id": "12345", "email": "jane@example.com" },
  "actionRunId": "<action-run-id>"
}

Every response — success or failure — carries an actionRunId. Pass it to GET /action-run-logs/{id} to inspect the resolved action, mapped input, raw HTTP exchange, and any errors. On failure the body still includes actionRunId alongside the error.

Replay from a run log

Every action run log carries an action field — the complete /act body that was used. Pass it back unchanged to re-run the same dispatch:

SNAPSHOT=$(curl -s https://api.integration.app/action-run-logs/<runId> \
  -H "Authorization: Bearer $TOKEN" | jq '.action')

curl -X POST https://api.integration.app/act \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$SNAPSHOT"

The snapshot is the source of truth for “what ran”. Top-level input and connectionId on the run log are deprecated — read them from action instead.

Legacy: `POST /actions/{selector}/run`

POST /actions/{selector}/run is the older endpoint for running a saved action. It still works for existing callers but is deprecated — /act covers all the same cases plus inline api and code dispatch.

Before	After
`POST /actions/<id>/run` body: `{ ...input }`	`POST /act` body: `{ "id": "<id>", "input": {...}, "connectionKey": "..." }`
`POST /actions/<key>/run?connectionId=<id>`	`POST /act` body: `{ "key": "<key>", "connectionId": "<id>", "input": {...} }`
Ad-hoc HTTP via a custom `run-javascript` action	`POST /act` body: `{ "api": { "method": "...", "path": "..." }, "connectionKey": "..." }`

Use /act for new code.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

string

ID of the action to run.

key

string

Key of the action to run. If the same key exists across multiple integrations, also pass integrationId, integrationKey, or connectionId so we know which one you mean.

api

object

Inline HTTP request spec, sent through the resolved connection's auth layer and base URL. Pair with connectionId, connectionKey, integrationId, or integrationKey to pick the connection.

Show child attributes

code

string

Inline JavaScript executed in a sandbox. The module must export a function that receives { input, membrane, ... }. Its return value becomes the action output.

integrationId

string

ID of the integration to run the action on. When key is provided, looks up the action within this integration. When no connection is specified, runs against this integration's default connection.

integrationKey

string

Key of the integration to run the action on. When key is provided, looks up the action within this integration. When no connection is specified, runs against this integration's default connection.

connectionId

string

ID of the connection to run the action against. If a connection-level version of the action exists on this connection, that version is used; otherwise the integration-level or universal action is used.

connectionKey

string

Key of the connection to run the action against. Use when you have a stable key for the connection instead of an ID.

input

any

Input passed to the action, matching its input schema.

Response

200 - application/json

output

object

actionRunId

string

Overview

Workspace Elements

Management API

Dispatch styles

Resolving a connection

Request body

Response

Replay from a run log

Legacy: `POST /actions/{selector}/run`

Authorizations

Body

Response

​Dispatch styles

​Resolving a connection

​Request body

​Response

​Replay from a run log

​Legacy: POST /actions/{selector}/run

Authorizations

Body

Response

Dispatch styles

Resolving a connection

Request body

Response

Replay from a run log

Legacy: `POST /actions/{selector}/run`